管理技能修订版本

在 Agent Registry 中，技能修订版本表示技能软件包的不可变版本化快照。当您更新技能的代码或指令时，系统会创建新的修订版本。这种解耦的架构支持对技能进行版本控制。

本文档介绍了如何创建和管理技能修订版本。如需了解如何更新特定技能的默认修订版本，请参阅更新技能元数据或默认修订版本。

准备工作

开始之前，请先设置 Agent Registry 并注册独立技能。您需要项目 ID 才能执行这些任务。

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

所需的角色

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

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

创建技能修订版本

创建新修订版本会将新的 ZIP 载荷上传到现有技能容器。创建技能修订版本后，该修订版本会自动成为技能的有效版本。不过，您可以随时更新技能的默认修订版本。只有有效修订版本才能下载。

技能修订版本的 ZIP 文件大小上限为 500 KB。

控制台

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

    前往 Agent Registry

  2. 选择技能标签页，然后点击技能的名称。
  3. 在技能详情页面中，找到版本记录表格。
  4. 点击 添加版本。

  5. 在添加版本面板中，选择以下选项之一：

    • 文件：上传包含代码或提示说明 (SKILL.md) 文件的软件包或 ZIP 文件。您可以点击浏览，在本地环境中查找文件。

    • 存储分区：提供包含有效 ZIP 软件包的 Cloud Storage URI (gs://...)。您可以点击浏览，在 Cloud Storage 存储分区中查找文件。

  6. 点击创建。

技能详情页面会在版本历史记录表格中显示技能修订版本。

gcloud

您可以通过上传本地 ZIP 文件或导入 Cloud Storage 中存储的软件包来创建技能修订版本。

替换以下内容：

  • REVISION_ID：您要分配给技能修订版本的 ID。
  • SKILL_ID：您用于修订的版本对应的技能的 ID。
  • PROJECT_ID：项目 ID。

  • LOCATION：注册表位置。

  • 上传本地 ZIP 文件：如需使用本地 ZIP 载荷创建技能修订版本，请执行以下操作：

    gcloud alpha agent-registry skills revisions create REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --payload="LOCAL_ZIP_PATH"

    将 LOCAL_ZIP_PATH 替换为本地计算机上打包的技能归档文件的路径。

  • 从 Cloud Storage 存储桶导入：如需使用 Cloud Storage 存储桶中托管的 ZIP 归档文件创建技能修订版本，请执行以下操作：

    gcloud alpha agent-registry skills revisions create REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

    替换以下内容：

    • BUCKET_NAME：包含 ZIP 软件包的 Cloud Storage 存储桶名称。
    • SKILL_PACKAGE：包含技能修订版本的技能软件包的名称。

REST

如需创建技能修订版本，请向修订版本集合发送 POST 请求。您可以直接上传 ZIP 载荷，也可以指向 Cloud Storage 路径。

  • 上传本地 ZIP 文件：在请求正文中指定包含 base64 编码 ZIP 字节的 archiveUploadSource。您可以在 curl 中使用内嵌的 base64 命令：

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "archiveUploadSource": {
          "archiveContent": "$(base64 -w0 local_skill.zip)"
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

  • 从 Cloud Storage 存储桶导入：在请求正文中指定 gcsSource，指向您的存储桶路径：

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "gcsSource": {
          "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

替换以下内容：

  • PROJECT_ID：项目 ID。
  • LOCATION：注册表位置。
  • SKILL_ID：技能容器的 ID。
  • REVISION_ID：您要为此修订版本分配的 ID。
  • BUCKET_NAME：包含 ZIP 文件的 Cloud Storage 存储桶名称。
  • SKILL_PACKAGE：ZIP 软件包的名称。

列出和描述修订版本

您可以查看技能的所有修订版本的列表，并检查其元数据。 如果您想更新技能的默认修订版本，请参阅更新技能元数据或默认修订版本。

如需列出并查看修订版本的详细信息，请按以下步骤操作：

控制台

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

    前往 Agent Registry

  2. 选择技能标签页，然后点击技能的名称。
  3. 在技能详情页面中，找到版本记录表格。
  4. 查看版本 ID、创建时间、修订状态和可用操作。

gcloud

如需列出技能的所有修订版本，请执行以下操作：

gcloud alpha agent-registry skills revisions list \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

如需描述特定修订版本的元数据，请执行以下操作：

gcloud alpha agent-registry skills revisions describe REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

REST

如需列出修订版本，请执行以下操作：

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions"

如需获取单个修订版本的元数据，请执行以下操作：

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

下载修订版本载荷

您可以下载特定修订版本的已编译 ZIP 文件载荷，以便进行本地验证或调试。

如需下载载荷，必须满足以下两个条件：

如需下载有效修订版本的修订版本载荷，请按以下步骤操作：

控制台

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

    前往 Agent Registry

  2. 选择技能标签页，然后点击技能的名称。
  3. 在技能详情页面中，找到版本记录表格。
  4. 找到要下载的修订版本。
  5. 在“操作”列中，点击下载。ZIP 载荷会下载到您的本地机器。

gcloud

如需下载修订版本的归档载荷，请运行带有 --alt=media 标志的 describe 命令，并将输出重定向到文件：

gcloud alpha agent-registry skills revisions describe REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --flags="alt=media" > skill_payload.zip

REST

向修订版本的资源网址发送 GET 请求，并添加查询参数 alt=media。您必须将 -L 标志与 curl 搭配使用，以跟踪 HTTP 重定向流：

curl -L -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -o skill_payload.zip \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID?alt=media"

删除特定修订版本

删除特定修订版本会从 Agent Registry 中移除其 ZIP 载荷和元数据历史记录。

删除单个修订版本通常仅限于管理员。您无法删除设为技能默认修订版本的修订版本。如需更新技能的默认修订版本，请参阅更新技能元数据或默认修订版本。

如需删除特定修订版本，请按以下步骤操作：

控制台

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

    前往 Agent Registry

  2. 选择技能标签页，然后点击技能的名称。
  3. 在技能详情页面中，找到版本记录表格。
  4. 找到要删除的修订版本。
  5. 在“操作”列中，点击删除并确认操作。

gcloud

gcloud alpha agent-registry skills revisions delete REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

REST

curl -X DELETE \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

后续步骤