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

管理代理

要有效管理代理群组，您需要随着 AI 生态系统的发展，查看和更新代理详细信息，覆盖元数据或移除不再使用的代理，从而保持注册表的准确性。

本文档详细介绍了如何查看和修改已注册代理的详细信息和配置。

准备工作

在管理代理之前，请确保您的代理已在 Agent Registry 中注册。您还需要项目 ID 才能执行这些任务。

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

所需的角色

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

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

探索可用的代理

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

列出并查看所有代理

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

控制台

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

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

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

gcloud

如需列出特定位置中的所有代理，请使用 agents list 命令：

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

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册区域。

过滤已注册的代理

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

控制台

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

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

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

gcloud

使用 --filter 标志过滤代理列表，以仅返回与特定元数据匹配的资源：

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

将 FILTER_EXPRESSION 替换为要过滤的代理的过滤表达式。例如，您可以使用以下过滤器：

如需按显示名称过滤，请使用 displayName='DISPLAY_NAME'。
如需按全局唯一标识符 (URN) 进行搜索，请使用 agentId='urn:agent:AGENT_URN'。

Terraform

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

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

替换以下内容：

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

查看代理的详细信息

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

控制台

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

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

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

详情页面包含用于显示代理详情的标签页。
点击相应标签页即可查看特定客服人员的详细信息。

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

gcloud

如需查看特定代理的详细元数据，请使用 agents describe 命令：

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

将 AGENT_NAME 替换为您的代理名称，例如 my-custom-agent。

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 API，Agent 资源用于发现。因此，您必须直接更新已注册的 Service 资源。

控制台

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

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

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

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

gcloud

使用带有特定标志的 gcloud CLI 修改代理的参数：

更新显示名称和说明：使用 --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
```
替换以下内容：
- ENDPOINT_URL：新的代理端点网址，例如 https://new-api.example.com/agent。
- PROTOCOL：端点的协议绑定。有效值为 http-json、grpc 或 jsonrpc。
更新代理的规范：使用 --agent-spec-type 和 --agent-spec-content 标志，例如，如果您有新的代理卡片：
```
gcloud agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@AGENT_SPEC_FILE
```
将 AGENT_SPEC_FILE 替换为新代理规范文件的路径，例如 new-agent-card.json。请注意，向 --agent-spec-content 传递文件路径时需要使用 @ 前缀。规范文件的最大大小为 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.remote-service.com/v1/agents/1234。
PROTOCOL：端点的协议绑定。有效值为 HTTP_JSON、GRPC 或 JSONRPC。

移除代理

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

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

控制台

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

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

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

gcloud

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

后续步骤

管理代理