管理技能

借助 Agent Registry,您可以检查、更新和管理独立技能,从而控制智能体可以使用哪些技能版本和生命周期状态。注册独立技能后,您可以查看其详细信息、更新其说明或默认修订版本、转换其生命周期状态、管理资源级访问权限政策,或将其从 Agent Registry 中删除。您还可以列出和查看 Google 管理的 skill,这些 skill 在您设置 Agent Registry 后即可使用。

准备工作

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

  3. 注册独立技能。

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

所需的角色

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

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

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

其他 Agent Registry 角色也可能包含查看、更新和删除技能所需的权限。如需了解详情,请参阅 Agent Registry 角色和权限。

列出和查看 skill

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

控制台

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

    前往 Agent Registry

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

gcloud

如需列出某个位置中的所有技能,请使用 gcloud agent-registry skills list 命令:

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

如需查看特定技能的详细信息,请使用 gcloud agent-registry skills describe 命令:

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

替换以下内容:

  • SKILL_ID:您要查看的技能的 ID。 对于手动注册的技能,请添加 private- 前缀,例如 private-my-skill。
  • PROJECT_ID:项目 ID。
  • LOCATION:注册表位置。

REST

如需检索所有技能的列表,请发送 GET 请求:

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

如需检索单个技能容器,请发送 GET 请求:

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

替换以下内容:

  • PROJECT_ID:项目 ID。
  • LOCATION:注册表位置。
  • SKILL_ID:您要查看的技能的 ID。 对于手动注册的技能,请添加 private- 前缀,例如 private-my-skill。

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

您可以修改技能的显示名称、说明、扫描配置,也可以手动更改默认修订版本指针以部署其他版本。

如果您的技能配置了 ENABLED_BLOCKING 扫描政策,则尝试将默认修订版本设置为具有安全发现结果或待处理扫描结果的修订版本时,会失败并显示 FAILED_PRECONDITION 错误。同样,如果技能的当前默认修订版本有安全发现结果或待处理的扫描结果,您就无法将其扫描政策更新为 ENABLED_BLOCKING。在技能上启用或更新扫描功能仅适用于在该更改之后创建的修订版本,不会追溯扫描现有修订版本。如需了解详情,请参阅扫描技能是否存在安全问题。 如需创建新的技能修订版本,请参阅管理技能修订版本。

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

控制台

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

    前往 Agent Registry

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

    • 更新技能元数据:

      1. 点击 修改。
      2. 在修改技能面板中,更新技能的显示名称或说明。
      3. 点击保存。
    • 更新默认修订版本:

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

gcloud

  • 如需更新技能的元数据,请使用 gcloud agent-registry skills update 命令:

    gcloud agent-registry skills update SKILL_ID \
        --project=PROJECT_ID \
        --location=LOCATION \
        --display-name="DISPLAY_NAME" \
        --description="DESCRIPTION"
    
  • 如需更新技能的默认服务修订版本,请使用 gcloud agent-registry skills update 命令并指定目标修订版本的资源名称:

    gcloud 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。 对于手动注册的技能,请添加 private- 前缀,例如 private-my-skill。
  • 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/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,defaultRevision"

替换以下内容:

  • DISPLAY_NAME:技能的更新显示名称。
  • DESCRIPTION:技能的更新说明。
  • PROJECT_ID:项目 ID。
  • LOCATION:注册表位置。
  • SKILL_ID:要更新的技能的 ID。 对于手动注册的技能,请添加 private- 前缀,例如 private-my-skill。
  • REVISION_ID:要激活的技能修订版本的 ID。

管理技能生命周期状态

如需控制技能在运行时的提供方式,您可以更改技能的目标状态以进行生命周期转换。

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

控制台

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

    前往 Agent Registry

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

gcloud

使用 gcloud agent-registry skills update 命令和 --target-state 标志更新技能容器:

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

替换以下内容:

  • SKILL_ID:要更新的技能的 ID。 对于手动注册的技能,请添加 private- 前缀,例如 private-my-skill。
  • PROJECT_ID:项目 ID。
  • LOCATION:注册表位置。

目标状态的允许值包括:

  • 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/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=targetState"

替换以下内容:

  • PROJECT_ID:项目 ID。
  • LOCATION:注册表位置。
  • SKILL_ID:要更新的技能的 ID。 对于手动注册的技能,请添加 private- 前缀,例如 private-my-skill。

目标状态的允许值包括:

  • TARGET_STATE_DRAFT
  • TARGET_STATE_ACTIVE
  • TARGET_STATE_DISABLED
  • TARGET_STATE_DEPRECATED
  • TARGET_STATE_DECOMMISSIONED

管理对技能的访问权限

当您注册技能时,Agent Registry 会自动在 Skill 资源上配置资源级 IAM 允许政策,向您的主账号授予 Agent Registry API Admin (roles/agentregistry.admin) 角色。如果您的项目属于某个组织,Agent Registry 还会向项目中代理工作负载授予 Agent Registry API Viewer (roles/agentregistry.viewer) 角色。

如需与其他用户、群组、服务账号或代理身份共享技能,而不授予项目级访问权限,您可以管理 Skill 资源上的资源级 IAM 政策。例如,您可以授予 Agent Registry API Viewer 角色,以便主账号可以查看、搜索和下载技能;也可以授予 Agent Registry API Editor 角色,以便主账号可以更新技能和上传新修订版本。您还可以对项目级 IAM 绑定配置 IAM Conditions,以限制对特定 Skill 和 SkillRevision 资源的访问。

如需查看或更新技能的 IAM 政策,请执行以下操作:

gcloud

  • 如需查看某项技能的当前 IAM 政策,请运行 gcloud agent-registry skills get-iam-policy 命令:

    gcloud agent-registry skills get-iam-policy SKILL_ID \
        --project=PROJECT_ID \
        --location=LOCATION
    
  • 如需向主账号授予技能角色,请运行 gcloud agent-registry skills add-iam-policy-binding 命令:

    gcloud agent-registry skills add-iam-policy-binding SKILL_ID \
        --project=PROJECT_ID \
        --location=LOCATION \
        --member="PRINCIPAL" \
        --role="ROLE"
    
  • 如需撤消主账号对技能的角色,请运行 gcloud agent-registry skills remove-iam-policy-binding 命令:

    gcloud agent-registry skills remove-iam-policy-binding SKILL_ID \
        --project=PROJECT_ID \
        --location=LOCATION \
        --member="PRINCIPAL" \
        --role="ROLE"
    
  • 如需使用本地 JSON 或 YAML 政策文件替换技能的 IAM 政策,请运行 gcloud agent-registry skills set-iam-policy 命令:

    gcloud agent-registry skills set-iam-policy SKILL_ID POLICY_FILE \
        --project=PROJECT_ID \
        --location=LOCATION
    

替换以下内容:

  • SKILL_ID:技能的 ID,包括 private- 前缀,例如 private-my-skill。
  • PROJECT_ID:项目 ID。
  • LOCATION:注册表位置。
  • PRINCIPAL:主账号标识符,例如 user:user@example.com 或 serviceAccount:my-sa@example-project.iam.gserviceaccount.com。
  • ROLE:要授予或撤销的 Agent Registry 角色,例如 roles/agentregistry.viewer 或 roles/agentregistry.editor。
  • POLICY_FILE:包含 IAM 政策定义的 JSON 或 YAML 文件的路径。

REST

  • 如需检索技能的当前 IAM 政策,请向 skills:getIamPolicy 端点发送 GET 请求:

    curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID:getIamPolicy"
    
  • 如需更新技能的 IAM 政策,请向 skills:setIamPolicy 端点发送 POST 请求,其中包含现有政策中的 etag:

    curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
          "policy": {
            "bindings": [
              {
                "role": "ROLE",
                "members": [
                  "PRINCIPAL"
                ]
              }
            ],
            "etag": "ETAG"
          }
        }' \
        "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID:setIamPolicy"
    

替换以下内容:

  • PROJECT_ID:项目 ID。
  • LOCATION:注册表位置。
  • SKILL_ID:技能的 ID,包括 private- 前缀,例如 private-my-skill。
  • ROLE:要授予的 Agent Registry 角色,例如 roles/agentregistry.viewer 或 roles/agentregistry.editor。
  • PRINCIPAL:主账号标识符,例如 user:user@example.com 或 serviceAccount:my-sa@example-project.iam.gserviceaccount.com。
  • ETAG:skills:getIamPolicy 返回的 etag 字符串。

删除技能

删除技能容器会永久删除 Skill 资源和所有关联的不可变 SkillRevision 资源。尝试解析已删除的技能标识符的代理会在运行时失败。

控制台

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

    前往 Agent Registry

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

gcloud

如需删除技能,请使用 gcloud agent-registry skills delete 命令:

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

替换以下内容:

  • SKILL_ID:要删除的技能的 ID。 对于手动注册的技能,请添加 private- 前缀,例如 private-my-skill。
  • PROJECT_ID:项目 ID。
  • LOCATION:注册表位置。

REST

如需删除技能,请发送 DELETE 请求:

curl -X DELETE \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?force=true"

替换以下内容:

  • PROJECT_ID:项目 ID。
  • LOCATION:注册表位置。
  • SKILL_ID:要删除的技能的 ID。 对于手动注册的技能,请添加 private- 前缀,例如 private-my-skill。

后续步骤