对于托管在Google Cloud 之外或在不受支持的运行时上运行的代理，您需要在代理注册表中手动注册。本文档介绍了如何在代理注册表中手动注册代理。
准备工作
开始之前，请先设置代理注册表。您需要项目 ID 才能执行这些任务。
如需使用本文档中的 Google Cloud CLI 命令，请确保您已设置 gcloud CLI 环境。
所需的角色
如需获得在代理注册表中手动注册代理所需的权限，请让您的管理员为您授予项目的 Agent Registry API Editor (roles/agentregistry.editor) IAM 角色。
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。
注册符合 A2A 标准的代理
如果您的远程代理实现了 Agent2Agent (A2A) 规范，请将代理注册表直接指向代理的 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 资源。使用 A2A_AGENT_CARD 类型和表示代理卡片 JSON 载荷的 content 指定 agent_spec 块：
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 规范的远程代理（例如标准 REST 或 SaaS API 端点），Agent Registry API 会创建一个没有代理协议规范的 Service 资源。
请按照以下步骤注册代理：
控制台
在 Google Cloud 控制台中，前往 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。
验证注册
注册代理后，验证代理注册表是否已成功处理 Service 并创建相应的 Agent 资源：
控制台
在 Google Cloud 控制台中，前往 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
使用 google_agent_registry_agent 数据源在其他 Terraform 配置中引用已注册的代理：
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：智能体的直观易懂的显示名称。