注册技能

借助 Agent Registry,您可以打包和手动注册独立技能。独立技能将智能体指令与关联的元数据资源和可选脚本捆绑在一起,以扩展智能体的推理和工作流。通过在 Agent Registry 中注册您自己的独立 skill,您可以集中管理、控制版本和共享可重用功能,以及在设置 Agent Registry 时可用的 Google 管理的 skill。

准备工作

  1. 设置 Agent Registry。
  2. 对于单项目设置,请获取已启用 Agent Registry 的治理项目的项目 ID。如果您为多个项目配置了管理边界,请使用管理项目的 ID 进行边界范围内的发现和注册,或指定成员项目 ID 进行单项目操作。

  3. 如需使用本文档中的 Google Cloud CLI 命令,请设置 gcloud CLI 环境。

所需的角色

如需获得在 Agent Registry 中注册技能所需的权限,请让管理员向您授予已启用 Agent Registry 的治理项目的以下 IAM 角色:

如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

其他 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 价格。

如需注册技能,请执行以下操作:

控制台

  1. 在 Google Cloud 控制台中,前往 Agent Registry 页面:

    前往 Agent Registry

  2. 从项目选择器中,选择您的 Google Cloud 项目。

  3. 选择技能标签页。

  4. 在技能标签页中,添加技能按钮会显示两个选项,分别用于创建技能容器和导入初始技能包。请从下列做法中选择一种:

    • 添加技能:在注册表中创建新的技能容器。您可以选择上传技能包以创建第一个修订版本。
    • 导入技能:通过上传包含 SKILL.md 指令文件和可选脚本的 ZIP 压缩包或独立的 SKILL.md 文件,注册新的自定义技能包。
  5. 在创建技能或导入技能面板中,指定以下详细信息:

    • 显示名称:输入技能的人性化名称。
    • 说明:输入简要说明,解释技能功能。
    • 位置:选择地理区域,例如 global、us 或 eu。
  6. 在载荷来源部分中,选择以下选项之一:

    • 文件:在上传软件包或文件字段中上传打包的技能 ZIP 归档文件或独立的 SKILL.md 文件。上传大小上限为 1 MB。您可以从本地目录中浏览该文件。
    • GCS 存储桶:在 Cloud Storage URI 字段中输入存储在 Cloud Storage 存储桶中的 ZIP 归档文件的路径。上传大小上限为 1 MB。路径必须采用 gs://BUCKET_NAME/SKILL_PACKAGE.zip 格式。

  7. 点击创建。

    您的技能是在已停用 (DISABLED) 状态下创建的。对于所有后续技能操作,请将您的技能称为 private-SKILL_ID,如Google Cloud 控制台中所示。

  8. 如需使技能可供代理发现,请设置其默认修订版本,并将目标状态更新为活跃。如需查看相关说明,请参阅管理技能。

gcloud

  1. 使用 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:简要说明技能功能。
  2. 如果您在创建技能时未指定初始修订版本,则只能将目标状态 (--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

  1. 创建技能容器,并以内嵌方式指定初始修订版本:

    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 正文替换为相应的字段和值。

  2. 当您创建具有初始修订版本的技能时,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) 角色。

如需与其他用户、群组、服务账号或代理工作负载共享技能,请参阅管理对技能的访问权限。

后续步骤