对于在外部托管 Google Cloud 或在不受支持的运行时上运行的代理，您需要在 Agent Registry 中手动注册。本文档介绍了如何在 Agent Registry 中手动注册代理。
准备工作
开始之前，请先设置 Agent Registry。您需要 项目 ID 才能执行这些任务。
如需使用本文档中的 Google Cloud CLI 命令，请确保您已 设置 gcloud CLI 环境。
所需角色
如需获得在 Agent Registry 中手动注册代理所需的权限，请让您的管理员为您授予项目的Agent Registry API Editor (roles/agentregistry.editor) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。
您也可以通过自定义 角色或其他预定义 角色来获取所需的权限。
注册符合 A2A 标准的代理
如果您的远程代理实现了 Agent2Agent (A2A) 规范，
请将 Agent Registry 指向代理的 agent-card.json 载荷。注册表
会自动同步
代理卡片，并为发现功能编入
代理的可用 A2A 技能 的索引。
请按照以下步骤注册代理：
控制台
在 Google Cloud 控制台中，前往 Agent Registry：
在项目选择器中，选择您在其中 设置 Agent Registry的 Google Cloud 项目。
选择代理 标签页。
点击添加代理 。
在代理详细信息 面板中，输入以下详细信息：
- 类型：选择 A2A。
- 区域：选择您要在其中注册 代理的地理位置。
请从下列选项中选择一项：
- 如需使用代理的 资源 URI 注册代理，请选择 来自 URI 标签页，然后在 URI 字段中输入有效网址。然后，点击导入 以从网址获取代理卡片。
- 如需复制并粘贴代理卡片内容，请选择粘贴 JSON 标签页，然后粘贴
agent-card.json文件的完整内容。
点击保存 。
gcloud
如需注册 A2A 智能体，请将智能体的智能体卡片另存为本地 JSON 文件（例如 agent-card.json），然后执行以下操作：
gcloud agent-registry services create AGENT_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--agent-spec-type=a2a-agent-card \
--agent-spec-content=agent-card.json
规范文件的文件大小上限为 10 KB。
替换以下内容：
AGENT_NAME：您要为代理指定的名称，例如my-support-agent。PROJECT_ID：项目 ID。REGION：您要在其中注册代理的区域 。如果您不想使用特定区域，请使用值global。DISPLAY_NAME：您要为代理指定的简单易懂的名称，例如Support Agent。
Terraform
如需注册符合 A2A 标准的代理，请配置 google_agent_registry_service 资源。指定 agent_spec 块，其中包含 A2A_AGENT_CARD 类型和表示代理卡片 JSON 载荷的 content：
resource "google_agent_registry_service" "a2a_agent" {
location = "REGION"
service_id = "AGENT_NAME"
display_name = "DISPLAY_NAME"
agent_spec {
type = "A2A_AGENT_CARD"
content = jsonencode({
schemaVersion = "v1"
displayName = "DISPLAY_NAME"
description = "A custom support agent registered using Terraform."
skills = [
{
name = "customer_lookup"
description = "Looks up customer info by email address."
}
]
})
}
}
output "agent_resource_name" {
description = "The generated read-only Agent resource name."
value = google_agent_registry_service.a2a_agent.registry_resource
}
替换以下内容：
REGION：您在其中注册代理的区域。AGENT_NAME：您要为代理指定的唯一名称，例如my-support-agent。DISPLAY_NAME：您要为代理指定的简单易懂的名称，例如Support Agent。
注册标准 REST 代理
标准 REST 代理可通过名称和 说明进行发现，但除非采用 A2A协议，否则不具备可搜索的A2A 技能。
如果您要注册未实现 A2A 规范的远程代理（例如标准 REST 或 SaaS API 端点），Agent Registry API 会创建一个没有代理协议规范的
Service 资源。
请按照以下步骤注册代理：
控制台
在 Google Cloud 控制台中，前往 Agent Registry：
在项目选择器中，选择您在其中 设置 Agent Registry的 Google Cloud 项目。
选择代理 标签页。
点击添加代理 。
在代理详细信息 面板中，输入以下详细信息：
- 类型：选择 Non-A2A。
- 名称：输入代理的简单易懂的显示名称，例如
Travel Agent。 - 说明：输入代理的功能说明，例如
A test agent that plans travel itineraries. - 区域：选择您要在其中注册 代理的地理位置。
- 端点：输入代理的托管端点。
点击保存 。
gcloud
您可以选择使用 --interfaces 标志提供定义的 HTTP/JSON 端点接口，以便注册表与代理建立连接。
如需注册标准 REST 代理，请执行以下操作：
gcloud agent-registry services create AGENT_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--agent-spec-type=no-spec \
--interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL
替换以下内容：
AGENT_NAME：您要为代理指定的名称，例如my-remote-rest-agent。PROJECT_ID：项目 ID。REGION：注册表区域。DISPLAY_NAME：您要为代理指定的简单易懂的名称，例如Remote REST Agent。ENDPOINT_URL：代理的 API 端点网址，例如https://api.remote-service.com/v1/agents/1234。PROTOCOL：端点的协议绑定。 有效值为HTTP_JSON、GRPC或JSONRPC。
Terraform
如需注册标准 REST 代理，请配置 google_agent_registry_service 资源，并将 agent_spec 设置为
NO_SPEC 类型，然后定义端点接口连接：
resource "google_agent_registry_service" "rest_agent" {
location = "REGION"
service_id = "AGENT_NAME"
display_name = "DISPLAY_NAME"
description = "A standard REST agent registered using Terraform."
agent_spec {
type = "NO_SPEC"
}
interfaces {
url = "ENDPOINT_URL"
protocol_binding = "PROTOCOL"
}
}
output "agent_resource_name" {
description = "The generated read-only Agent resource name."
value = google_agent_registry_service.rest_agent.registry_resource
}
替换以下内容：
REGION：您在其中注册代理的区域。AGENT_NAME：您要为代理指定的唯一名称，例如my-remote-rest-agent。DISPLAY_NAME：您要为代理指定的简单易懂的名称，例如Remote REST Agent。ENDPOINT_URL：代理的 API 端点网址，例如https://api.remote-service.com/v1/agents/1234。PROTOCOL：端点的协议绑定。 有效值为HTTP_JSON、GRPC或JSONRPC。
验证注册情况
注册代理后，请验证 Agent Registry 是否已成功处理 Service 并创建相应的 Agent 资源：
控制台
在 Google Cloud 控制台中，前往 Agent Registry：
在项目选择器中，选择您在其中 设置 Agent Registry的 Google Cloud 项目。
选择代理 标签页。
该页面必须显示所有已注册代理及其详细信息的列表。
gcloud
gcloud agent-registry agents list \
--project=PROJECT_ID \
--location=REGION
如果您有多个代理，或者想要确认单个代理的注册情况，可以按代理的元数据过滤列表：
gcloud agent-registry agents list \
--project=PROJECT_ID \
--location=REGION \
--filter="FILTER_EXPRESSION"
替换以下内容：
Terraform
如需在其他 Terraform 配置中引用已注册的代理，请使用 google_agent_registry_agent 数据源：
data "google_agent_registry_agent" "my_agent" {
location = "REGION"
filter = "displayName=\"DISPLAY_NAME\""
}
output "agent_urn" {
value = data.google_agent_registry_agent.my_agent.urn
}
替换以下内容：
REGION：注册表区域。DISPLAY_NAME：代理的简单易懂的显示名称。