管理技能

在 Agent Registry 中注册独立技能后，您可以查看其详细信息、更新其说明、替换其有效修订版本指针 (default_revision)、管理其生命周期状态，或从 Agent Registry 中将其删除。您还可以列出并查看 Google 创建的技能，这些技能在您设置 Agent Registry 后会立即显示。

本文档介绍了如何执行这些管理任务。

准备工作

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

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

所需的角色

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

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

列出和查看技能

您可以浏览所有已注册的技能，也可以搜索特定功能：

控制台

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

    前往 Agent Registry

  2. 选择技能标签页。
  3. 查看技能列表。您可以使用位置或状态菜单过滤显示内容。
  4. 点击任意技能名称以打开其技能详情页面，其中会显示名称、说明、有效版本、技能 URN、上次更新时间、自定义元数据和修订历史记录。

gcloud

如需列出某个位置的所有技能，请执行以下操作：

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

如需查看特定技能的详细信息，请执行以下操作：

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

替换以下内容：

  • SKILL_ID：您要查看的技能的 ID。
  • PROJECT_ID：项目 ID。
  • LOCATION：注册表位置。

REST

如需检索所有技能的列表，请执行以下操作：

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

如需检索单个技能容器，请执行以下操作：

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

替换以下内容：

  • PROJECT_ID：项目 ID。
  • LOCATION：注册表位置。
  • SKILL_ID：您要查看的技能的 ID。

更新技能元数据或默认修订版本

您可以修改技能的显示名称、说明，也可以手动更改默认修订版本指针以部署其他版本。如需创建新的技能修订版本，请参阅管理技能修订版本。

如需更新技能元数据或特定技能的默认修订版本，请按以下步骤操作：

控制台

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

    前往 Agent Registry

  2. 选择技能标签页。
  3. 查看技能列表。您可以使用位置或状态菜单过滤显示内容。
  4. 点击任意技能名称以打开其技能详情页面，其中会显示名称、说明、有效版本、技能 URN、上次更新时间、自定义元数据和修订历史记录。

  5. 从以下选项中进行选择：

    • 更新技能元数据：

      1. 点击 修改。
      2. 在修改技能面板中，更新技能的显示名称或说明。
      3. 点击保存。

    • 更新默认修订版本：

      1. 找到版本历史记录表格。
      2. 找到要设为有效版本的修订版本。
      3. 在操作列中，点击启用版本。

gcloud

  • 如需更新技能的元数据，请执行以下操作：

    gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION"

  • 如需更新技能的默认服务修订版本，请执行以下操作：

    gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --default-revision="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

替换以下内容：

  • SKILL_ID：要更新的技能的 ID。
  • PROJECT_ID：项目 ID。
  • LOCATION：注册表位置。
  • DISPLAY_NAME：更新后的显示名称。
  • DESCRIPTION：更新后的说明。
  • REVISION_ID：您要设置为默认技能修订版本的 ID。

REST

发送 PATCH 请求，指定要更新的字段：

curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "displayName": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        "defaultRevision": "projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,defaultRevision"

替换以下内容：

  • DISPLAY_NAME：技能的更新后的显示名称。
  • DESCRIPTION：技能的更新说明。
  • PROJECT_ID：项目 ID。
  • LOCATION：注册表位置。
  • SKILL_ID：要更新的技能的 ID。
  • REVISION_ID：您要激活的技能修订版本的 ID。

管理技能生命周期状态

如需控制技能在运行时的解析方式，您可以更改技能的目标状态：

  • 草稿：技能处于初始创建或开发阶段。它不会在运行时提供，并且载荷下载会被阻止。在此状态下，您可以随意修改技能配置和载荷，然后再将技能升级到 Active 目标状态。
  • 有效：技能已提供，且完全可解析。
  • 已停用：立即无法解析技能，并会阻止下载。与已停用状态不同，您可以稍后重新启用技能，这意味着将其恢复为有效目标状态。
  • 已弃用：技能仍可加载，但会返回警告标头，表明该技能即将被弃用。
  • 已停用：技能已被永久停用，不再提供服务，且无法恢复为有效或任何其他状态。只有在技能已被弃用后，才能将其停用。在停用技能之前，请预留足够的时间进行迁移。这是一个最终状态，建议您谨慎使用。

如需转换技能的生命周期状态，请执行以下操作：

控制台

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

    前往 Agent Registry

  2. 选择技能标签页。
  3. 查看技能列表。您可以使用位置或状态菜单过滤显示内容。
  4. 点击任意技能名称以打开其技能详情页面，其中会显示名称、说明、有效版本、技能 URN、上次更新时间、自定义元数据和修订历史记录。
  5. 使用状态控制按钮转换目标状态。页面上显示的按钮取决于技能的当前状态，例如启用、停用、弃用或停用。

gcloud

使用 --target-state 标志更新技能容器：

gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --target-state=DISABLED

目标状态的允许值包括：

  • DRAFT
  • ACTIVE
  • DISABLED
  • DEPRECATED
  • DECOMMISSIONED。

REST

发送 PATCH 请求，在正文和更新掩码中指定 targetState：

curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "targetState": "TARGET_STATE_DISABLED"
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=targetState"

目标状态的允许值包括：

  • TARGET_STATE_DRAFT
  • TARGET_STATE_ACTIVE
  • TARGET_STATE_DISABLED
  • TARGET_STATE_DEPRECATED
  • TARGET_STATE_DECOMMISSIONED。

删除技能

删除技能容器会永久删除该技能容器和所有关联的不可变 SkillRevision 版本记录。尝试解析已删除技能 URN 的代理会在运行时失败。

控制台

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

    前往 Agent Registry

  2. 选择技能标签页。
  3. 查看技能列表。您可以使用位置或状态菜单过滤显示内容。
  4. 点击要删除的技能的名称。
  5. 在技能详情页面中，点击 删除。
  6. 在确认对话框中，输入 DELETE，然后点击删除。

gcloud

gcloud alpha agent-registry skills delete 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?force=true"

后续步骤