Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

管理代理

借助智能体注册表，您可以检查、更新和移除已注册的智能体，以便注册表准确反映 AI 生态系统中的活跃功能。您可以列出和查看所有已注册的智能体、更新手动注册的智能体的元数据或端点，以及移除不再使用的智能体。

准备工作

设置 Agent Registry。
对于单项目设置，请获取已启用 Agent Registry 的治理项目的项目 ID。如果您为多个项目配置了管理边界，请使用管理项目的 ID 进行边界范围内的发现和注册，或指定成员项目 ID 进行单项目操作。
在 Agent Registry 中注册您的智能体。
如需使用本文档中的 Google Cloud CLI 命令，请设置 gcloud CLI 环境。

所需的角色

如需获得在 Agent Registry 中管理已注册代理所需的权限，请让管理员向您授予已启用 Agent Registry 的治理项目的 Agent Registry API Editor (roles/agentregistry.editor) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

探索可用的智能体

注册代理后，您可以在环境中发现它们并查看其详细配置，例如其端点、A2A 技能和关联的元数据。

列出并查看所有代理

您可以列出环境中注册的所有代理，并查看其详细配置，例如端点、A2A 技能和关联的元数据。

如果您配置了管理边界，则可以从管理项目中列出多个成员项目中的代理。

如需列出代理，请按以下步骤操作：

控制台

在 Google Cloud 控制台中，前往 Agent Registry：

前往 Agent Registry
在项目选择器中，选择您设置 Agent Registry 的 Google Cloud 项目。
选择代理标签页。

页面上会显示所有已注册代理的列表。该列表包含代理的名称、标识符、类型、说明、版本、运行时和位置。
如需查看代理的完整详细信息，请点击代理的名称。

gcloud

如需列出特定位置中的所有代理，请运行 gcloud agent-registry agents list 命令：

gcloud agent-registry agents list \
    --project=PROJECT_ID \
    --location=REGION

替换以下内容：

PROJECT_ID：项目 ID。如果您配置了管理边界，请指定管理项目的 ID，以列出边界内所有成员项目中指定位置的智能体。每个返回的资源名称都会保留代理的 ID，并使用请求中指定的项目。
REGION：注册表位置，例如 us-central1、eu 或 global。在管理项目中，指定位置会汇总边界内所有成员项目中同一位置的代理。

过滤已注册的代理

如果您有多个代理，或者想要确认特定代理的注册，则可以按代理的元数据过滤列表：

控制台

在 Google Cloud 控制台中，前往 Agent Registry：

前往 Agent Registry
在项目选择器中，选择您设置 Agent Registry 的 Google Cloud 项目。
选择代理标签页。

页面上会显示所有已注册代理的列表。该列表包含代理的名称、标识符、类型、说明、版本、运行时和位置。
按代理的位置或其运行时资源过滤列表：
- 如需按位置过滤，请点击位置菜单，选择要过滤的位置，然后点击应用。
- 如需按运行时进行过滤，请点击运行时菜单，选择要过滤的运行时，然后点击应用。
该页面会显示符合所选条件的已注册代理的过滤列表。

gcloud

通过将 --filter 标志传递给 gcloud agent-registry agents list 命令，过滤代理列表，以便仅返回与特定元数据匹配的资源：

gcloud agent-registry agents list \
    --project=PROJECT_ID \
    --location=REGION \
    --filter="FILTER_EXPRESSION"

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册表区域。
FILTER_EXPRESSION：要过滤的智能体的过滤表达式。例如，您可以使用以下过滤条件：
- 如需按显示名称进行过滤，请使用 displayName='DISPLAY_NAME'。
- 如需按全局唯一的代理标识符 (URN) 进行搜索，请使用 agentId='urn:agent:AGENT_URN'。
- 如需在查询管理项目时按特定成员项目进行过滤，请使用 project_id=MEMBER_PROJECT_ID。

Terraform

如需通过过滤元数据来检索特定注册代理，请使用 filter 参数配置 google_agent_registry_agent 数据源：

data "google_agent_registry_agent" "filtered_agent" {
  location = "REGION"
  filter   = "displayName=\"DISPLAY_NAME\""
}

替换以下内容：

REGION：注册表区域。
DISPLAY_NAME：要作为过滤条件的代理的人类可读名称，例如 Support Agent。

查看智能体详情

查看特定智能体的详细信息，包括其协议、A2A 技能和身份：

控制台

在 Google Cloud 控制台中，前往 Agent Registry：

前往 Agent Registry
在项目选择器中，选择您设置 Agent Registry 的 Google Cloud 项目。
选择代理标签页。

页面上会显示所有已注册代理的列表。该列表包含代理的名称、标识符、类型、说明、版本、运行时和位置。
点击您要查看的代理的名称。

详情页面包含代理详情标签页。
点击相应标签页即可查看特定代理的详细信息。

功能可用性取决于您的运行时。会话、Playground、记忆和评估等标签页是针对在托管式运行时（例如 Gemini Enterprise Agent Platform 上的 Agent Runtime）上构建的智能体显示的特定功能：
- 概览：智能体的核心详细信息，包括智能体的名称、标识符、位置、说明和运行时。概览还会显示 A2A 技能和运行时参考，您需要这些信息才能在拓扑图中构建查询。
- 可观测性：以应用为中心的数据洞见，例如延迟时间、流量、错误和 token 支出。此标签页与 Google Cloud Observability 工具集成，可显示实时性能指标和系统级利用率，帮助您管理费用和用户体验。如需了解详情，请参阅可观测性概览。
- 跟踪记录：对话的分步确切路径，包括输入和助理消息的详细格式，以便实时调试复杂的多智能体推理循环或工具调用错误。如需了解详情，请参阅查看代理跟踪记录。
- 安全性：Model Armor 和 Security Command Center 的发现结果，包括内容政策违规、数据泄露风险和合规性评估。如需详细了解安全性，请参阅查看安全发现结果。
- 拓扑：直观呈现代理、其分配的 Agent Gateway 以及与其交互的 MCP 服务器之间的关系和流量。如需详细了解 Agent Gateway，请参阅 Agent Gateway 概览。如需详细了解拓扑，请参阅查看已注册代理的图表。
- 身份：用于执行政策的智能体主体。您可以使用此身份来配置身份验证提供方绑定，以便对工具和资源进行身份验证。
- 会话：永久性对话记录以及与智能体的活跃互动跟踪。
- Playground：一个直接对话界面，用于测试智能体的行为。
- 记忆：长期个性化功能，可生成或回忆与智能体过往对话中的细节，以便在多次互动中保留上下文。
- 评估：所有智能体评估任务的详细信息。在此标签页中，您可以创建新的评估任务、上传指标，并根据实时流量或合成模拟评估智能体的认知表现和模型可靠性。

gcloud

如需查看特定代理的详细元数据，请运行 gcloud agent-registry agents describe 命令：

gcloud agent-registry agents describe AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION

替换以下内容：

AGENT_NAME：代理的名称，例如 my-custom-agent。
PROJECT_ID：项目 ID。在管理边界中，您可以指定管理项目 ID 或部署了代理的成员项目的 ID。返回的资源名称会保留智能体的 ID，并使用请求中指定的项目。
REGION：注册表区域。

Terraform

如需使用 ID 检索特定注册代理的详细信息，请配置 google_agent_registry_agent 数据源：

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  agent_id = "AGENT_ID"
}

output "agent_create_time" {
  description = "The timestamp when the agent was registered."
  value       = data.google_agent_registry_agent.my_agent.create_time
}

output "agent_update_time" {
  description = "The timestamp when the agent was last updated."
  value       = data.google_agent_registry_agent.my_agent.update_time
}

替换以下内容：

REGION：注册表区域。
AGENT_ID：代理的唯一标识符，例如 my-custom-agent。

更新代理元数据和端点

如果代理的运行时网址发生变化，或者您想替换其显示名称、说明或规范，可以更新代理元数据。

在 Agent Registry 中，Agent 资源是只读发现资源。如需更新手动注册的代理，您必须直接更新其可写 Service 资源，方法是指定注册该 Service 资源的项目 ID。对于自动注册的智能体，请在其底层运行时中更新智能体，以便 Agent Registry 同步更改。

控制台

通过 Google Cloud 控制台更新可用的代理详情：

在 Google Cloud 控制台中，前往 Agent Registry：

前往 Agent Registry
在项目选择器中，选择您设置 Agent Registry 的 Google Cloud 项目。
选择代理标签页。

页面上会显示所有已注册代理的列表。该列表包含代理的名称、标识符、类型、说明、版本、运行时和位置。
点击要更新的代理的名称。
在代理的概览标签页中，点击修改。
在修改服务面板中，输入代理的更新信息，例如其新名称或说明。
点击保存。

gcloud

运行带有特定标志的 gcloud agent-registry services update 命令，以修改代理的参数：

更新显示名称和说明：使用 --display-name 和 --description 标志，例如：

gcloud agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="New display name" \
    --description="Updated description of the agent's purpose."

替换以下内容：

AGENT_NAME：代理的名称，例如 my-support-agent。
PROJECT_ID：项目 ID。
REGION：注册表区域。

更新端点网址：使用 --interfaces 标志指定新端点，例如：
```
gcloud agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL
```
替换以下内容：
- AGENT_NAME：代理的名称，例如 my-support-agent。
- PROJECT_ID：项目 ID。
- REGION：注册表区域。
- ENDPOINT_URL：新的 Agent Endpoint，例如 https://new-api.example.com/agent。
- PROTOCOL：端点的协议绑定。有效值为 http-json、grpc 或 jsonrpc。
更新智能体的规范：使用 --agent-spec-content 标志，例如，如果您有新的智能体卡片：
```
gcloud agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --agent-spec-content=AGENT_SPEC_FILE
```
替换以下内容：
- AGENT_NAME：代理的名称，例如 my-support-agent。
- PROJECT_ID：项目 ID。
- REGION：注册表区域。
- AGENT_SPEC_FILE：新代理规范文件的路径，例如 new-agent-card.json。规范文件的文件大小上限为 10 KB。

Terraform

如需更新已注册智能体的元数据、端点网址或规范，请修改配置中现有 google_agent_registry_service 资源的参数，然后运行 terraform apply：

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "New Display Name"
  description  = "Updated description of the agent's purpose."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

替换以下内容：

REGION：注册表区域。
AGENT_NAME：您要为代理指定的唯一名称，例如 my-support-agent。
ENDPOINT_URL：代理的 API 端点网址，例如 https://api.example.com/v1/agents/1234。
PROTOCOL：端点的协议绑定。有效值为 HTTP_JSON、GRPC 或 JSONRPC。

移除代理

如需删除自动注册到 Agent Registry 的代理，您必须在其特定 Google Cloud 运行时中删除底层代理。然后，系统会自动从注册表中移除该代理。

如需从注册表中移除手动注册的代理，您必须通过指定注册该 Service 资源的项目 ID 来删除其 Service 资源。此操作会从搜索结果中移除该智能体，并使其无法被其他工具发现：

控制台

在 Google Cloud 控制台中，前往 Agent Registry：

前往 Agent Registry
在项目选择器中，选择您设置 Agent Registry 的 Google Cloud 项目。
选择代理标签页。

页面上会显示所有已注册代理的列表。该列表包含代理的名称、标识符、类型、说明、版本、运行时和位置。
点击要移除的代理的名称。
在代理的概览标签页中，点击删除。
在确认对话框中，输入 DELETE 以确认操作。
点击删除。

gcloud

运行 gcloud agent-registry services delete 命令：

gcloud agent-registry services delete AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION

替换以下内容：

AGENT_NAME：要移除的代理的名称，例如 my-support-agent。
PROJECT_ID：项目 ID。
REGION：注册表区域。

Terraform

从 Terraform 配置中移除代表代理的 google_agent_registry_service 资源，然后运行 terraform apply。

后续步骤

了解如何使用拓扑图查看代理关系。
了解如何使用自然语言查询搜索智能体、工具和技能。

管理代理 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

探索可用的智能体

列出并查看所有代理

控制台

gcloud

过滤已注册的代理

控制台

gcloud

Terraform

查看智能体详情

控制台

gcloud

Terraform

更新代理元数据和端点

控制台

gcloud

Terraform

移除代理

控制台

gcloud

Terraform

后续步骤

管理代理