注册技能

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

准备工作

  1. 设置 Agent Registry。

  2. 获取已启用 Agent Registry 的治理项目的项目 ID。

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

所需的角色

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

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

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

其他 Agent Registry 角色可能还包含注册和管理技能及技能修订版本所需的权限。如需了解详情，请参阅 Agent Registry 角色和权限。

提取载荷限制

如需注册技能，您必须将技能的源文件打包到 ZIP 归档文件中。归档文件的根目录中必须包含 SKILL.md 指令文件。在技能注册流程的提取阶段，Agent Registry 会验证载荷是否符合以下限制：

  • ZIP 归档文件大小：压缩后的归档文件大小上限为 500 KB。
  • 未压缩载荷总大小：未压缩大小上限为 10 MB。
  • 单个文件大小：每个文件的未压缩大小上限为 1 MB。
  • 深度嵌套：目录嵌套深度上限为 8 层。
  • 规范合规性：SKILL.md 文件必须包含有效的 YAML 前置元数据部分，其中定义了智能体技能规范中定义的名称、说明和元数据。

注册技能

您可以在 Agent Registry 中手动注册自己的技能。如需了解技能的价格和功能费用，请参阅 Agent Registry 价格。

如需注册您的技能，请执行以下操作：

控制台

  1. 在 Google Cloud 控制台中，前往智能体注册表页面：

    前往 Agent Registry

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

  3. 选择技能标签页。

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

    • 添加技能：在注册表中创建新的技能容器。您可以选择上传技能包来创建第一个修订版本。
    • 导入技能：上传包含 SKILL.md 指令文件和可选脚本的 ZIP 压缩包，以注册新的自定义技能包。

  5. 在创建技能或导入技能面板中，指定以下详细信息：

    • 显示名称：输入技能的人性化名称。
    • 说明：输入简要说明，解释技能功能。
    • 位置：选择地理区域，例如 global、us 或 eu。

  6. 在载荷来源部分中，选择以下选项之一：

    • 文件：拖动打包的技能 ZIP 文件，或浏览本地目录。

    • 存储桶：输入存储在 Cloud Storage 存储桶中的 ZIP 归档文件的路径，格式为 gs://BUCKET_NAME/SKILL_PACKAGE.zip。

  7. 点击创建。

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

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

gcloud

  1. 使用 gcloud alpha agent-registry skills create 命令创建技能容器并上传其初始修订版本载荷。您可以上传本地 ZIP 文件，也可以导入存储在 Cloud Storage 中的软件包：

    • 上传本地 ZIP 文件：如需使用本地 ZIP 载荷注册技能，请执行以下操作：

      gcloud alpha 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 alpha 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. 新创建的技能最初处于已停用 (DISABLED) 状态。如需使技能可供代理发现，请设置其默认修订版本，并将目标状态更新为活跃。如需查看相关说明，请参阅管理技能生命周期状态。

REST

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

    HTTP 方法和网址

    POST https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID

    替换以下内容：

    • PROJECT_ID：项目 ID。
    • LOCATION：注册表位置。
    • SKILL_ID：技能容器的唯一标识符。

    请求 JSON 正文（本地文件上传）

    如需通过直接上传本地 ZIP 归档文件字节来创建技能，请使用 archiveUploadSource 载荷。在创建期间，必须将 targetState 设置为 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/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

    替换以下内容：

    • DISPLAY_NAME：技能的人性化名称。
    • DESCRIPTION：简要说明技能功能。
    • PROJECT_ID：项目 ID。
    • LOCATION：注册表位置。
    • SKILL_ID：技能容器的唯一标识符。

    对于 Cloud Storage 存储桶文件上传，请将请求 JSON 正文替换为相应的字段和值。

  2. 新创建的技能最初处于已停用 (DISABLED) 状态。如需使技能可供代理发现，请设置其默认修订版本，并将目标状态更新为活跃。如需查看相关说明，请参阅管理技能生命周期状态。

您或其他用户创建的 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。

后续步骤