建立及管理技能

本指南說明如何使用 REST API，在技能登錄中建立、更新及管理技能。

事前準備

使用技能登錄檔前，請先設定環境：

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform API.

    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

  5. 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 Google Cloud 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 Google Cloud 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 email address for a Google Account.

    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.

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

  7. Verify that billing is enabled for your Google Cloud project.

  8. Enable the Agent Platform API.

    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

  9. 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 Google Cloud 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 Google Cloud 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 email address for a Google Account.

    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.

法規遵循

下表彙整了合規狀態：

功能 狀態
資料存取透明化控管機制 支援
美國和歐盟的資料落地 (DRZ) 功能 支援
Customer-Managed Encryption Keys (CMEK) 不支援
《健康保險流通與責任法案》(HIPAA) 認證 不支援
VPC-SC 不支援

可用地區

技能註冊服務適用於下列地區：

區域 位置
us-central1 愛荷華州
europe-west4 荷蘭
us-east5 俄亥俄州哥倫布

建立技能

如要建立新技能，請使用 CreateSkill 方法。這項作業是長時間執行的作業。

如需預期技能結構的範例，請參閱 Google Cloud Skills 存放區中的 SKILL.md 檔案。

REST

以下章節說明如何使用 REST API 建立技能。

準備酬載

呼叫 API 前，請先將技能檔案封裝成 ZIP 封存檔，並編碼為單行 base64 字串。如要準備酬載，請按照下列步驟操作：

  1. 前往技能目錄：

    cd <SKILL_DIRECTORY>

  2. 建立 zip 封存檔，並以 base64 編碼。

    例如：

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

要求變數

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 專案 ID。

  • LOCATION：技能的區域。詳情請參閱「適用區域」。

  • SKILL_ID：SKILL_ID 一旦建立後即無法變更，且會永久保留，即使日後刪除技能也一樣。技能 ID 必須遵守下列限制：

    • 長度必須介於 1 至 63 個字元之間。
    • 只能使用小寫英文字母、數字和連字號。
    • 開頭須為英文字母，結尾則須為英文字母或數字。
    • 開頭不得為 gcp- (這個前置字串保留給內建技能使用)。

  • DISPLAY_NAME：與代理程式搭配使用的技能名稱。RetrieveSkills 方法會使用顯示名稱和說明搜尋相關技能。

  • DESCRIPTION：說明技能的用途。

  • BASE64_ZIPPED_BODY：以 Base64 編碼的壓縮技能封存內容。

HTTP 方法和網址

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

JSON 要求內文

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

curl 指令

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

在本地目錄中整理技能檔案 (例如 SKILL.md、說明和程式碼檔案)。SDK 支援傳遞本機目錄路徑 (系統會自動壓縮) 或預先壓縮的路徑。

適用於 google-cloud-aiplatform (提供 agentplatform) 1.154.0 以上版本：

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)

適用於 google-cloud-aiplatform (提供 agentplatform) 舊版，版本低於 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

在本地目錄中整理技能檔案 (例如 SKILL.md、說明和程式碼檔案)。SDK 支援傳遞本機目錄路徑 (系統會自動壓縮) 或預先壓縮的路徑。

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);

更新技能

如要更新現有技能，請使用 UpdateSkill 方法。這項作業是長時間執行的作業。

你可以更新現有技能的顯示名稱、說明和有效負載 (壓縮的檔案系統)。只有 updateMask 查詢參數中列出的欄位會更新。

REST

以下章節說明如何使用 REST API 更新技能。

準備酬載

選用。如要更新技能檔案，請將更新後的技能檔案封裝成壓縮檔，並編碼為單行 base64 字串：

  1. 前往技能目錄：

    cd <SKILL_DIRECTORY>

  2. 建立 zip 封存檔，並以 base64 編碼：

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

要求變數

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：技能的區域。詳情請參閱「適用區域」。
  • SKILL_ID：要更新的技能 ID。
  • DISPLAY_NAME：選用。技能的新名稱。
  • DESCRIPTION：選用。這項技能的新說明。
  • BASE64_ZIPPED_BODY：選用。更新後的壓縮技能封存檔的 Base64 編碼內容。

HTTP 方法和網址

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

JSON 要求內文

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

curl 指令

下列 curl 指令會更新顯示名稱、說明和壓縮的技能檔案。

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 支援傳遞未壓縮的本機目錄路徑或預先壓縮的路徑，藉此更新技能檔案。

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 支援傳遞未壓縮的本機目錄路徑或預先壓縮的路徑，藉此更新技能檔案。

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);

列出技能

如要擷取特定位置的技能摘要中繼資料 (包括名稱、顯示名稱和說明)，請使用 ListSkills 方法。

REST

以下章節說明如何使用 REST API 列出技能。

要求變數

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：要列出技能的區域。詳情請參閱「適用區域」。

HTTP 方法和網址

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

curl 指令

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"

輸出範例

{
"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);
}

取得技能

如要擷取技能最新版本的元資料和酬載，請使用 GetSkill 方法。

REST

以下章節說明如何使用 REST API 取得技能。

要求變數

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：技能所在的區域。詳情請參閱「適用區域」。
  • SKILL_ID：要擷取的技能 ID。

HTTP 方法和網址

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

curl 指令

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);

刪除技能

如要刪除技能和所有修訂版本，請使用 DeleteSkill 方法。 這項作業是長時間執行的作業。

REST

以下章節說明如何使用 REST API 刪除技能。

要求變數

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：要刪除的技能所在的區域。詳情請參閱「適用區域」。
  • SKILL_ID：要刪除的技能 ID。

HTTP 方法和網址

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

curl 指令

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',
});

列出技能修訂版本

如要擷取特定技能的修訂版本記錄，請使用 ListSkillRevisions 方法。

REST

以下各節說明如何使用 REST API 列出技能修訂版本。

要求變數

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：所需技能所在的區域。詳情請參閱「適用區域」。
  • SKILL_ID：技能 ID。

HTTP 方法和網址

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

curl 指令

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"

輸出範例

{
  "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);
}

取得技能修訂版本

如要擷取技能的特定修訂版本，請使用 GetSkillRevision 方法。

REST

以下章節說明如何使用 REST API 取得技能修訂版本。

要求變數

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：技能的區域。詳情請參閱「適用區域」。
  • SKILL_ID：技能 ID。
  • REVISION_ID：要擷取的特定修訂版本 ID。這項資訊位於 ListSkillRevisions 方法傳回的 name 欄位中。舉例來說，如果 name 是 projects/1234567890/locations/us-central1/skills/cymbal-skill/revisions/4567890123，則修訂版本 ID 為 4567890123。

HTTP 方法和網址

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

curl 指令

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);

擷取技能

使用 RetrieveSkills 方法，透過語意搜尋尋找技能。舉例來說，您可以描述想完成的工作 (例如 find skills to manage cloud resources)，然後搜尋相關技能。

REST

以下章節說明如何使用 REST API 擷取技能。

要求變數

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：要搜尋的技能所在區域。詳情請參閱「適用區域」。
  • QUERY：用來尋找相符技能的查詢字串。

HTTP 方法和網址

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

curl 指令

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);
}

取得長時間執行的作業詳細資料

Skill Registry API 的部分方法 (例如 CreateSkill、UpdateSkill 和 DeleteSkill) 為非同步，且會傳回長時間執行的作業。長時間執行的作業是一種 API 模式，適用於可能需要相當長的時間才能完成的作業。API 會傳回作業資源，而不是等待作業完成。

這些方法的回應包含 name 欄位，其中含有作業 ID。舉例來說，name 可能如下所示： projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/operations/OPERATION_ID。

如要檢查長時間執行的作業的狀態並取得詳細資料，請使用 GetOperation 方法和擷取的 OPERATION_ID。

REST

以下各節說明如何使用 REST API 取得作業。

要求變數

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：作業執行的區域。這必須與初始要求中使用的區域相符。詳情請參閱「適用區域」。
  • OPERATION_ID：作業 ID。從 CreateSkill、UpdateSkill 或 DeleteSkill 傳回的 name 欄位中擷取這項資訊。

HTTP 方法和網址

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

curl 指令

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"

後續步驟

指南

瞭解如何使用 Agent Platform 的 Managed Agents API 建立或更新代理時，附加已註冊的技能。

指南

瞭解如何在 ADK 中整合技能登錄。