借助 Agent Registry,您可以打包和手动注册独立技能。独立技能将智能体指令与关联的元数据资源和可选脚本捆绑在一起,以扩展智能体的推理和工作流。通过在 Agent Registry 中注册您自己的独立 skill,您可以集中管理、控制版本和共享可重用功能,以及在设置 Agent Registry 时可用的 Google 管理的 skill。
准备工作
- 设置 Agent Registry。
对于单项目设置,请获取已启用 Agent Registry 的治理项目的项目 ID。如果您为多个项目配置了管理边界,请使用管理项目的 ID 进行边界范围内的发现和注册,或指定成员项目 ID 进行单项目操作。
如需使用本文档中的 Google Cloud CLI 命令,请设置 gcloud CLI 环境。
所需的角色
如需获得在 Agent Registry 中注册技能所需的权限,请让管理员向您授予已启用 Agent Registry 的治理项目的以下 IAM 角色:
-
注册和管理独立技能:Agent Registry User (
roles/agentregistry.user) -
注册和管理独立技能及其他 Agent Registry 资源:
Agent Registry API Editor (
roles/agentregistry.editor)
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
其他 Agent Registry 角色也可能包含注册和管理技能及技能修订版本所需的权限。如需了解详情,请参阅 Agent Registry 角色和权限。
提取载荷限制
如需注册 skill,您必须将 skill 的源文件打包到 ZIP 归档文件中。归档文件的根目录中必须包含 SKILL.md 指令文件。在 skill 注册流程的提取阶段,Agent Registry 会验证载荷是否符合以下限制:
- ZIP 归档文件大小:压缩归档文件大小上限为 1 MB。
- 未压缩载荷总大小:启用扫描时,未压缩大小上限为 10 MB。
- 单个文件大小:启用扫描功能时,每个文件的解压缩后大小上限为 1 MB。
- 深度嵌套:目录嵌套深度上限为 8 层。
- 规范合规性:
SKILL.md文件必须包含有效的 YAML 前置元数据部分,其中定义了智能体技能规范中定义的名称、说明和元数据。
使用 ENABLED_BLOCKING 或 ENABLED_NONBLOCKING 扫描政策启用自动扫描后,如果超出解压缩大小上限,会导致修订版本创建失败并显示 INVALID_ARGUMENT 错误,或导致修订版本的扫描状态转换为 UNSUPPORTED_FORMAT。如果停用扫描,Agent Registry 会绕过这些特定于扫描的限制。如需配置扫描政策并详细了解载荷大小限制,请参阅扫描技能以查找安全问题。
注册技能
您可以在 Agent Registry 中手动注册自己的技能。如需了解技能的价格和功能费用,请参阅 Agent Registry 价格。
如需注册技能,请执行以下操作:
控制台
在 Google Cloud 控制台中,前往 Agent Registry 页面:
从项目选择器中,选择您的 Google Cloud 项目。
选择技能标签页。
在技能标签页中,添加技能按钮会显示两个选项,分别用于创建技能容器和导入初始技能包。请从下列做法中选择一种:
- 添加技能:在注册表中创建新的技能容器。您可以选择上传技能包以创建第一个修订版本。
- 导入技能:通过上传包含
SKILL.md指令文件和可选脚本的 ZIP 压缩包或独立的SKILL.md文件,注册新的自定义技能包。
在创建技能或导入技能面板中,指定以下详细信息:
- 显示名称:输入技能的人性化名称。
- 说明:输入简要说明,解释技能功能。
- 位置:选择地理区域,例如
global、us或eu。
在载荷来源部分中,选择以下选项之一:
- 文件:在上传软件包或文件字段中上传打包的技能 ZIP 归档文件或独立的
SKILL.md文件。上传大小上限为 1 MB。您可以从本地目录中浏览该文件。 GCS 存储桶:在 Cloud Storage URI 字段中输入存储在 Cloud Storage 存储桶中的 ZIP 归档文件的路径。上传大小上限为 1 MB。路径必须采用
gs://BUCKET_NAME/SKILL_PACKAGE.zip格式。
- 文件:在上传软件包或文件字段中上传打包的技能 ZIP 归档文件或独立的
点击创建。
您的技能是在已停用 (
DISABLED) 状态下创建的。对于所有后续技能操作,请将您的技能称为private-SKILL_ID,如Google Cloud 控制台中所示。
gcloud
使用
gcloud agent-registry skills create命令创建技能容器并上传其初始修订版本载荷。您可以上传本地 ZIP 文件,也可以导入存储在 Cloud Storage 中的软件包:上传本地 ZIP 文件:如需使用本地 ZIP 载荷注册技能,请执行以下操作:
gcloud agent-registry skills create SKILL_ID \ --project=PROJECT_ID \ --location=LOCATION \ --display-name="DISPLAY_NAME" \ --description="DESCRIPTION" \ --target-state=disabled \ --payload="LOCAL_ZIP_PATH"将
LOCAL_ZIP_PATH替换为本地机器上打包的技能归档文件的路径,例如./workspace-docs-skill.zip。从 Cloud Storage 存储桶导入:使用 Cloud Storage 存储桶中托管的 ZIP 归档文件注册技能:
gcloud agent-registry skills create SKILL_ID \ --project=PROJECT_ID \ --location=LOCATION \ --display-name="DISPLAY_NAME" \ --description="DESCRIPTION" \ --target-state=disabled \ --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"替换以下内容:
BUCKET_NAME:包含 ZIP 软件包的 Cloud Storage 存储桶名称。SKILL_PACKAGE:包含技能载荷的技能包的名称。
在任一命令中替换以下内容:
SKILL_ID:技能的资源 ID,例如workspace-docs-skill。创建后,注册表会自动在前面添加private-前缀。您必须在所有后续技能命令中使用带前缀的 ID,例如private-workspace-docs-skill。PROJECT_ID:项目 ID。LOCATION:地理区域,例如global、us或eu。DISPLAY_NAME:技能的人性化名称。DESCRIPTION:简要说明技能功能。
如果您在创建技能时未指定初始修订版本,则只能将目标状态 (
--target-state) 设置为draft或disabled。当您创建具有初始修订版本的技能时(例如使用
--gcs-source-uri或--payload),Agent Registry 会将初始修订版本设置为技能的默认修订版本。您可以将目标状态设置为以下值之一,具体取决于扫描政策:- 如果
--target-state=active且扫描政策为disabled或enabled-nonblocking,则技能会在创建操作完成后转换为有效 (STATE_ACTIVE) 状态。 - 如果
--target-state=active且扫描政策为enabled-blocking(默认),则创建操作完成后,技能会进入草稿 (STATE_DRAFT) 状态。在后台,安全扫描完成后,只有在扫描未产生任何发现结果,且父级技能处于草稿状态,默认修订版本仍指向初始修订版本时,父级技能才会转换为有效 (STATE_ACTIVE)。 - 如果为
--target-state=disabled或--target-state=draft,您稍后可以通过设置有效的默认修订版本并将目标状态更新为有效,使其可供智能体发现。如需了解相关说明,请参阅管理技能。
- 如果
REST
创建技能容器,并以内嵌方式指定初始修订版本:
HTTP 方法和网址
POST https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID替换以下内容:
PROJECT_ID:项目 ID。LOCATION:注册表位置。SKILL_ID:技能容器的唯一标识符。
请求 JSON 正文(本地文件上传)
如需通过直接上传本地 ZIP 归档文件字节来创建技能,请在初始修订版本 (
initialRevision) 中使用archiveUploadSource载荷。提供初始修订版本后,Agent Registry 会将该修订版本设置为技能的默认修订版本。您可以将目标状态设置为TARGET_STATE_DRAFT、TARGET_STATE_DISABLED或TARGET_STATE_ACTIVE。如果没有初始修订版本,则仅支持TARGET_STATE_DRAFT和TARGET_STATE_DISABLED作为目标状态:{ "displayName": "DISPLAY_NAME", "description": "DESCRIPTION", "type": "SIMPLE", "targetState": "TARGET_STATE_DISABLED", "initialRevision": { "archiveUploadSource": { "archiveContent": "BASE64_ZIP_BYTES" } } }替换以下内容:
DISPLAY_NAME:技能的人性化名称。DESCRIPTION:简要说明技能功能。BASE64_ZIP_BYTES:本地 ZIP 归档文件的 base64 编码字符串表示。
请求 JSON 正文(从 Cloud Storage 导入)
或者,如需使用存储在 Cloud Storage 存储桶中的归档创建技能,请使用
gcsSource:{ "displayName": "DISPLAY_NAME", "description": "DESCRIPTION", "type": "SIMPLE", "targetState": "TARGET_STATE_DISABLED", "initialRevision": { "gcsSource": { "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip" } } }替换以下内容:
DISPLAY_NAME:技能的人性化名称。DESCRIPTION:简要说明技能功能。BUCKET_NAME:包含 ZIP 软件包的 Cloud Storage 存储桶名称。SKILL_PACKAGE:包含技能载荷的技能包的名称。
curl命令(本地文件上传)curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "displayName": "DISPLAY_NAME", "description": "DESCRIPTION", "type": "SIMPLE", "targetState": "TARGET_STATE_DISABLED", "initialRevision": { "archiveUploadSource": { "archiveContent": "'"$(base64 -w0 local_skill.zip)"'" } } }' \ "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"替换以下内容:
DISPLAY_NAME:技能的人性化名称。DESCRIPTION:简要说明技能功能。PROJECT_ID:项目 ID。LOCATION:注册表位置。SKILL_ID:技能容器的唯一标识符。
对于 Cloud Storage 存储桶文件上传,请将请求 JSON 正文替换为相应的字段和值。
当您创建具有初始修订版本的技能时,Agent Registry 会将初始修订版本设置为父技能的默认修订版本,并根据目标状态和扫描政策转换技能的状态:
- 如果目标状态为
TARGET_STATE_ACTIVE,且扫描政策为DISABLED或ENABLED_NONBLOCKING,则技能会在长时间运行的操作 (LRO) 完成后进入STATE_ACTIVE状态。 - 如果目标状态为
TARGET_STATE_ACTIVE,且扫描政策为ENABLED_BLOCKING(默认),则技能会在 LRO 完成时进入STATE_DRAFT状态。在后台,当安全扫描完成时,只有在扫描未产生任何发现结果且父级技能仍处于STATE_DRAFT状态且默认修订版本仍指向初始修订版本时,父级技能才会转换为STATE_ACTIVE。 - 如果目标状态为
TARGET_STATE_DISABLED或TARGET_STATE_DRAFT,则技能会从STATE_DISABLED或STATE_DRAFT开始。如需让技能稍后可供代理发现,您必须设置默认修订版本,并将目标状态更新为TARGET_STATE_ACTIVE。如需查看相关说明,请参阅管理技能。
- 如果目标状态为
您或其他用户创建的 skill 会自动分配给默认的 private 发布商,以避免与 Google 管理的 skill 发生名称冲突。因此,特定技能的已发布 ID 会变为 private-SKILL_ID。您无法在创建技能期间指定自定义发布者。
例如,如果您创建 ID 为 workspace-tools 的技能,则资源名称会创建为 projects/PROJECT_NUMBER/locations/LOCATION/skills/private-workspace-tools。技能标识符分配为 urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools。对于所有后续技能操作,您必须使用 private-workspace-tools 发布的 ID。
创建技能时,Agent Registry 会自动在新的 Skill 资源上配置资源级 IAM 允许政策:
- 您的主账号已被授予该技能的 Agent Registry API Admin (
roles/agentregistry.admin) 角色。 - 如果项目属于某个组织,则代表项目中代理工作负载的主账号集会被授予该技能的 Agent Registry API Viewer (
roles/agentregistry.viewer) 角色。
如需与其他用户、群组、服务账号或代理工作负载共享技能,请参阅管理对技能的访问权限。
后续步骤
- 了解如何管理已注册的技能。
- 了解如何添加和管理技能修订版本。
- 了解如何扫描技能以查找安全问题。
- 查看经过验证的发布商详细信息。