注册技能

在 Agent Registry 中，技能是指代理可以具备的独立的可执行能力。它包含 SKILL.md 文件中的指令、代码脚本和可扩展代理推理能力的资源。通过在 Agent Registry 中注册独立技能，您可以集中管理、版本控制和共享组织中 AI 智能体的功能。

设置 Agent Registry 后，您会立即看到 Google 创建的技能。本文档介绍了如何在 Agent Registry 中手动注册自己的独立技能。

准备工作

开始之前，请先设置代理注册表。您需要项目 ID 才能执行这些任务。

如需使用本文档中的 Google Cloud CLI 命令，请确保您已设置 gcloud CLI 环境。

所需的角色

如需获得在代理注册表中注册技能所需的权限，请让您的管理员为您授予项目的 Agent Registry User (roles/agentregistry.user) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

提取载荷限制

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

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

注册技能

设置 Agent Registry 后，您会立即看到 Google 创建的技能。不过，您也可以手动注册自己的技能。每个技能都有一个默认修订版本，并且可以包含多个已纳入版本控制的技能修订版本。

如需注册您自己的技能，您需要创建一个逻辑技能容器，并在一次操作中上传初始修订版本载荷。之后，您可以管理已注册的技能及其后续的技能修订版本。

您或其他用户创建的技能会自动分配给默认的 private 发布者，以避免与 Google 创建的技能发生名称冲突。因此，特定技能的已发布 ID 会变为 private-SKILL_ID。您无法在技能创建期间指定自定义发布者。

例如，如果您创建 ID 为 workspace-tools 的技能，则资源名称将创建为 projects/PROJECT_ID/locations/LOCATION/skills/private-workspace-tools。逻辑统一资源名称 (URN) 分配为 urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools。 您必须使用此已发布的 ID (private-workspace-tools) 来执行所有后续技能操作。

如需注册技能，请按以下步骤操作：

控制台

  1. 在 Google Cloud 控制台中，前往 Agent Registry 页面：

    前往 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. 点击创建。

您的技能已创建。对于所有后续技能操作，请将技能称为 private-SKILL_ID，如Google Cloud 控制台中所示。

gcloud

如需注册技能并上传其初始载荷，您可以上传本地 ZIP 文件，也可以导入存储在 Cloud Storage 中的软件包。

替换以下内容：

  • SKILL_ID：技能的资源 ID，例如 workspace-docs-skill。创建后，注册表会自动添加 private- 前缀。您必须在所有后续技能命令中使用带前缀的 ID，例如 private-workspace-docs-skill。
  • PROJECT_ID：项目 ID。
  • LOCATION：地理区域，例如 global、us 或 eu。
  • DISPLAY_NAME：技能的易记名称。

  • DESCRIPTION：简要说明技能的功能。

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

    gcloud alpha agent-registry skills create SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --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" \
  --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

    替换以下内容：

    • BUCKET_NAME：包含 ZIP 软件包的 Cloud Storage 存储桶名称。
    • SKILL_PACKAGE：包含技能载荷的技能软件包的名称。

REST

如需创建具有初始内嵌修订版本的技能，请执行以下操作：

HTTP 方法和网址

POST https://agentregistry.googleapis.com/v1alpha/projects/{project}/locations/{location}/skills?skillId={skillId}

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

如需通过直接上传本地 ZIP 归档字节来创建技能，请使用 archiveUploadSource 载荷：

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "archiveUploadSource": {
      "archiveContent": "BASE64_ZIP_BYTES"
    }
  }
}

将 BASE64_ZIP_BYTES 替换为本地 ZIP 归档的 base64 编码字符串表示形式。

请求 JSON 正文（从 Cloud Storage 导入）

或者，如需使用存储在 Cloud Storage 存储桶中的归档文件创建技能，请使用 gcsSource：

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "gcsSource": {
      "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
    }
  }
}

替换以下内容：

  • 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_ACTIVE",
        "initialRevision": {
          "archiveUploadSource": {
            "archiveContent": "$(base64 -w0 local_skill.zip)"
          }
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

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

后续步骤