Membuat dan mengelola keahlian

Panduan ini menjelaskan cara membuat, memperbarui, dan mengelola kemampuan di Skill Registry menggunakan REST API.

Sebelum memulai

Sebelum menggunakan Skill Registry, siapkan lingkungan Anda:

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: roles/aiplatform.viewer or roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer

    Check for the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

Kepatuhan

Tabel berikut merangkum status kepatuhan:

Fitur Status
Transparansi Akses Didukung
Residensi Data (DRZ) di Amerika Serikat dan Uni Eropa Didukung
Customer-Managed Encryption Keys (CMEK) Tidak Didukung
Sertifikasi HIPAA Tidak Didukung
VPC-SC Tidak Didukung

Wilayah yang tersedia

Skill Registry tersedia di wilayah berikut:

Wilayah Lokasi
us-central1 Iowa
europe-west4 Belanda
us-east5 Columbus, Ohio

Buat keahlian

Untuk membuat keahlian baru, gunakan metode CreateSkill. Operasi ini adalah operasi yang berjalan lama.

Untuk contoh struktur keterampilan yang diharapkan, lihat file SKILL.md di repositori Google Cloud Skills.

REST

Bagian berikut menjelaskan cara menggunakan REST API untuk membuat skill.

Menyiapkan payload

Sebelum memanggil API, kemas file skill Anda ke dalam arsip ZIP dan enkode ke dalam string base64 satu baris. Untuk menyiapkan payload, ikuti langkah-langkah berikut:

  1. Buka direktori skill Anda:

    cd <SKILL_DIRECTORY>

  2. Buat arsip zip dan encode ke base64.

    Contoh:

    zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip

Variabel permintaan

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.

  • LOCATION: Region untuk skill Anda. Untuk mengetahui informasi selengkapnya, lihat Region yang tersedia.

  • SKILL_ID: SKILL_ID tidak dapat diubah dan akan tetap dipesan secara permanen setelah dibuat, meskipun Anda menghapus skill tersebut nanti. ID skill harus mematuhi batasan berikut:

    • Harus terdiri dari 1 hingga 63 karakter.
    • Hanya boleh berisi huruf kecil, angka, dan tanda hubung.
    • Harus diawali dengan huruf dan diakhiri dengan huruf atau angka.
    • Tidak boleh diawali dengan gcp- (awalan ini dicadangkan untuk skill bawaan).

  • DISPLAY_NAME: Nama skill yang digunakan dengan agen. Metode RetrieveSkills menggunakan nama tampilan dan deskripsi untuk menelusuri keterampilan yang relevan.

  • DESCRIPTION: Deskripsi tentang fungsi skill.

  • BASE64_ZIPPED_BODY: Konten berenkode base64 dari arsip skill yang di-zip.

Metode HTTP dan URL

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID

Isi JSON permintaan

{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}

curl perintah

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "zippedFilesystem": "BASE64_ZIPPED_BODY"
    }' \
    "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

Python

Atur file keterampilan (seperti SKILL.md, petunjuk, dan file kode) di direktori lokal. SDK mendukung penerusan jalur direktori lokal (yang dikompresi secara otomatis) atau jalur yang telah di-zip sebelumnya.

Untuk google-cloud-aiplatform (yang menyediakan agentplatform) versi 1.154.0 dan yang lebih baru:

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.create(
    skill_id="SKILL_ID",
    display_name="DISPLAY_NAME",
    description="DESCRIPTION",
    config={
        # Local directory path (automatically compressed) or pre-zipped path (.zip)
        "local_path": "SKILL_PATH",
    },
)
print(skill.name)

Untuk versi google-cloud-aiplatform (yang menyediakan agentplatform) yang lebih lama dari 1.154.0:

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.create(
    display_name="DISPLAY_NAME",
    description="DESCRIPTION",
    config={
        "skill_id": "SKILL_ID",
        # Local directory path (automatically compressed) or pre-zipped path (.zip)
        "local_path": "SKILL_PATH",
    },
)
print(skill.name)

Node.js

Atur file keterampilan (seperti SKILL.md, petunjuk, dan file kode) di direktori lokal. SDK mendukung penerusan jalur direktori lokal (yang dikompresi secara otomatis) atau jalur yang telah di-zip sebelumnya.

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const skill = await client.skills.create({
  skillId: 'SKILL_ID',
  displayName: 'DISPLAY_NAME',
  description: 'DESCRIPTION',
  config: {
    // Local directory path (automatically compressed) or pre-zipped path (.zip)
    localPath: 'SKILL_PATH',
  },
});
console.log(skill.name);

Memperbarui keahlian

Untuk memperbarui skill yang ada, gunakan metode UpdateSkill. Operasi ini adalah operasi yang berjalan lama.

Anda dapat memperbarui nama tampilan, deskripsi, dan payload skill yang ada (sistem file yang di-zip). Hanya kolom yang tercantum dalam parameter kueri updateMask yang diperbarui.

REST

Bagian berikut menjelaskan cara menggunakan REST API untuk memperbarui skill.

Menyiapkan payload

Opsional. Jika Anda memperbarui file skill, kemas file skill yang diperbarui ke dalam arsip ber-zip dan encode ke dalam string base64 satu baris:

  1. Buka direktori skill Anda:

    cd <SKILL_DIRECTORY>

  2. Buat arsip zip dan encode ke base64:

    zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip

Variabel permintaan

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Region skill. Untuk mengetahui informasi selengkapnya, lihat Region yang tersedia.
  • SKILL_ID: ID skill yang akan diperbarui.
  • DISPLAY_NAME: Opsional. Nama baru untuk keahlian.
  • DESCRIPTION: Opsional. Deskripsi baru tentang fungsi skill.
  • BASE64_ZIPPED_BODY: Opsional. Konten berenkode base64 dari arsip skill terupdate yang di-zip.

Metode HTTP dan URL

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID

Isi JSON permintaan

{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}

curl perintah

Perintah curl berikut memperbarui nama tampilan, deskripsi, dan file skill yang di-zip.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "zippedFilesystem": "BASE64_ZIPPED_BODY"
    }' \
    "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,zippedFilesystem"

Python

SDK mendukung pembaruan file skill dengan meneruskan jalur direktori lokal yang belum di-unzip atau jalur yang sudah di-zip.

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.update(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID",
    config={
        "display_name": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        # Optional. Local directory path (automatically compressed) or pre-zipped path (.zip)
        "local_path": "SKILL_PATH",
    },
)
print(skill.name)

Node.js

SDK mendukung pembaruan file skill dengan meneruskan jalur direktori lokal yang belum di-unzip atau jalur yang sudah di-zip.

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const skill = await client.skills.update({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
  config: {
    displayName: 'DISPLAY_NAME',
    description: 'DESCRIPTION',
    // Optional. Local directory path (automatically compressed) or pre-zipped path (.zip)
    localPath: 'SKILL_PATH',
  },
});
console.log(skill.name);

Mencantumkan keterampilan

Untuk mengambil metadata ringkasan keterampilan di lokasi tertentu (termasuk nama, nama tampilan, dan deskripsi), gunakan metode ListSkills.

REST

Bagian berikut menjelaskan cara menggunakan REST API untuk mencantumkan keterampilan.

Variabel permintaan

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Region tempat skill yang ingin Anda cantumkan. Untuk mengetahui informasi selengkapnya, lihat Region yang tersedia.

Metode HTTP dan URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills

curl perintah

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills"

Contoh output

{
"name": "projects/1234567890/locations/us-central1/skills/3456789012",
"createTime": "2026-05-10T00:02:12.497720Z",
"updateTime": "2026-05-10T00:02:19.064874Z",
"displayName": "cymbal_skill",
"description": "A skill for managing Cymbal projects.",
"state": "ACTIVE"
}

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

pager = client.skills.list()
for skill in pager:
    print(skill.name, skill.display_name)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const pager = await client.skills.list();
for await (const skill of pager) {
  console.log(skill.name, skill.displayName);
}

Mendapatkan keahlian

Untuk mengambil metadata dan payload revisi terbaru skill, gunakan metode GetSkill.

REST

Bagian berikut menjelaskan cara menggunakan REST API untuk mendapatkan skill.

Variabel permintaan

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Region tempat skill berada. Untuk mengetahui informasi selengkapnya, lihat Region yang tersedia.
  • SKILL_ID: ID skill yang akan diambil.

Metode HTTP dan URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID

curl perintah

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.get(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)
print(skill)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const skill = await client.skills.get({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});
console.log(skill);

Menghapus keahlian

Untuk menghapus skill dan semua revisinya, gunakan metode DeleteSkill. Operasi ini adalah operasi yang berjalan lama.

REST

Bagian berikut menjelaskan cara menggunakan REST API untuk menghapus skill.

Variabel permintaan

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Region tempat skill yang ingin Anda hapus berada. Untuk mengetahui informasi selengkapnya, lihat Region yang tersedia.
  • SKILL_ID: ID skill yang akan dihapus.

Metode HTTP dan URL

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID

curl perintah

curl -X DELETE \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

client.skills.delete(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

await client.skills.delete({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});

Mencantumkan revisi keahlian

Untuk mengambil histori revisi untuk skill tertentu, gunakan metode ListSkillRevisions.

REST

Bagian berikut menjelaskan cara menggunakan REST API untuk mencantumkan revisi skill.

Variabel permintaan

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Region tempat keterampilan yang Anda inginkan berada. Untuk mengetahui informasi selengkapnya, lihat Region yang tersedia.
  • SKILL_ID: ID skill.

Metode HTTP dan URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions

curl perintah

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions"

Contoh output

{
  "skillRevisions": [
    {
      "name": "projects/1234567890/locations/us-central1/skills/cymbal_skill/revisions/4567890123",
      "createTime": "2026-05-10T00:02:12.497720Z",
      "updateTime": "2026-05-10T00:02:19.064874Z"
    }
  ]
}

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

response = client.skills.revisions.list(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)
for skill_revision in response.skill_revisions:
    print(skill_revision.name, skill_revision.create_time)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const response = await client.skills.revisions.list({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});
for (const revision of response.skillRevisions || []) {
  console.log(revision.name, revision.createTime);
}

Mendapatkan revisi keahlian

Untuk mengambil revisi tertentu dari skill, gunakan metode GetSkillRevision.

REST

Bagian berikut menjelaskan cara menggunakan REST API untuk mendapatkan revisi skill.

Variabel permintaan

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Region skill. Untuk mengetahui informasi selengkapnya, lihat Region yang tersedia.
  • SKILL_ID: ID skill.
  • REVISION_ID: ID revisi tertentu yang akan diambil. Hal ini dapat ditemukan di kolom name yang ditampilkan oleh metode ListSkillRevisions. Misalnya, jika name adalah projects/1234567890/locations/us-central1/skills/cymbal-skill/revisions/4567890123, ID revisinya adalah 4567890123.

Metode HTTP dan URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID

curl perintah

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

revision = client.skills.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
)
print(revision)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const revision = await client.skills.revisions.get({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID',
});
console.log(revision);

Mengambil keterampilan

Gunakan metode RetrieveSkills untuk menemukan keterampilan menggunakan penelusuran semantik. Misalnya, Anda dapat menelusuri keterampilan dengan mendeskripsikan tugas yang ingin Anda selesaikan, seperti find skills to manage cloud resources.

REST

Bagian berikut menjelaskan cara menggunakan REST API untuk mengambil keterampilan.

Variabel permintaan

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Region tempat keterampilan yang ingin Anda telusuri berada. Untuk mengetahui informasi selengkapnya, lihat Region yang tersedia.
  • QUERY: String kueri untuk menemukan keterampilan yang cocok.

Metode HTTP dan URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills:retrieve?query=QUERY

curl perintah

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills:retrieve?query=QUERY"

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

response = client.skills.retrieve(
    query="QUERY",
    config={"top_k": TOP_K},
)
for retrieved_skill in response.retrieved_skills:
    print(retrieved_skill.skill_name, retrieved_skill.description)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const response = await client.skills.retrieve({
  query: 'QUERY',
  config: {
    topK: TOP_K,
  },
});
for (const retrievedSkill of response.retrievedSkills || []) {
  console.log(retrievedSkill.skillName, retrievedSkill.description);
}

Mendapatkan detail operasi yang berjalan lama

Beberapa metode di Skill Registry API, seperti CreateSkill, UpdateSkill, dan DeleteSkill, bersifat asinkron dan menampilkan operasi yang berjalan lama. Operasi yang berjalan lama adalah pola API yang digunakan untuk operasi yang dapat memerlukan waktu yang cukup lama untuk diselesaikan. Alih-alih menunggu operasi selesai, API menampilkan resource operasi.

Respons dari metode ini mencakup kolom name, yang berisi ID operasi. Misalnya, name mungkin terlihat seperti ini: projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/operations/OPERATION_ID.

Untuk memeriksa status dan mendapatkan detail operasi yang berjalan lama, gunakan metode GetOperation dengan OPERATION_ID yang diekstrak.

REST

Bagian berikut menjelaskan cara menggunakan REST API untuk mendapatkan operasi.

Variabel permintaan

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Region tempat operasi berjalan. Region ini harus cocok dengan region yang digunakan dalam permintaan awal Anda. Untuk mengetahui informasi selengkapnya, lihat Region yang tersedia.
  • OPERATION_ID: ID operasi. Ekstrak ini dari kolom name yang ditampilkan oleh CreateSkill, UpdateSkill, atau DeleteSkill.

Metode HTTP dan URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

curl perintah

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

Langkah berikutnya

Panduan

Pelajari cara melampirkan skill terdaftar saat membuat atau memperbarui agen menggunakan Managed Agents API di Agent Platform.

Panduan

Pelajari cara mengintegrasikan dengan Skill Registry di ADK.