Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

创建和管理技能

本指南介绍了如何使用 REST API 在技能注册表中创建、更新和管理技能。

准备工作

在使用技能注册表之前，请设置您的环境：

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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
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

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 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.

合规性

下表总结了合规性状态：

功能	状态
Access Transparency	支持
美国和欧盟的数据驻留 (DRZ)	支持
客户管理的加密密钥 (CMEK)	不支持
HIPAA 认证	不支持
VPC-SC	不支持

可用区域

技能注册表可在以下区域使用：

区域	位置
`us-central1`	爱荷华
`europe-west4`	荷兰
`us-east5`	俄亥俄州，哥伦布

创建技能

如需创建新技能，请使用 CreateSkill 方法。此操作是一项长时间运行的操作。

如需查看预期技能结构的示例，请参阅 SKILL.md 文件，这些文件位于 Google Cloud Skills 代码库中。

REST

以下部分介绍了如何使用 REST API 创建技能。

准备载荷

在调用 API 之前，请将技能文件打包到压缩归档文件中，并将其编码为单行 base64 字符串。如需准备载荷，请按以下步骤操作：

前往技能目录：
```
cd <SKILL_DIRECTORY>
```

创建压缩归档文件并将其编码为 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 字符串：

前往技能目录：
```
cd <SKILL_DIRECTORY>
```

创建压缩归档文件并将其编码为 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。您可以在 name 字段中找到此 ID，此字段由ListSkillRevisions 方法返回。例如，如果 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);
}

获取长时间运行的操作的详细信息

技能注册表 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 字段中提取此 ID。

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"

后续步骤

指南

将技能附加到智能体

了解如何在智能体平台上使用 Managed Agents API 创建或更新智能体时附加已注册的技能。

指南

ADK 技能注册表集成

了解如何在 ADK 中与技能注册表集成。

创建和管理技能 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

Check for the roles

Grant the roles

合规性

可用区域

创建技能

REST

准备载荷

请求变量

HTTP 方法和网址

请求 JSON 正文

curl 命令

Python

Node.js

更新技能

REST

准备载荷

请求变量

HTTP 方法和网址

请求 JSON 正文

curl 命令

Python

Node.js

列出技能

REST

请求变量

HTTP 方法和网址

curl 命令

输出示例

Python

Node.js

获取技能

REST

请求变量

HTTP 方法和网址

curl 命令

Python

Node.js

删除技能

REST

请求变量

HTTP 方法和网址

curl 命令

Python

Node.js

列出技能修订版本

REST

请求变量

HTTP 方法和网址

curl 命令

输出示例

Python

Node.js

获取技能修订版本

REST

请求变量

HTTP 方法和网址

curl 命令

Python

Node.js

检索技能

REST

请求变量

HTTP 方法和网址

curl 命令

Python

Node.js

获取长时间运行的操作的详细信息

REST

请求变量

HTTP 方法和网址

curl 命令

后续步骤

将技能附加到智能体

ADK 技能注册表集成

创建和管理技能

`curl` 命令

`curl` 命令

`curl` 命令

`curl` 命令

`curl` 命令

`curl` 命令

`curl` 命令

`curl` 命令

`curl` 命令