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

使用手动注册

对于托管在Google Cloud之外、在不受支持的运行时上运行或部署在不同 Google Cloud 项目中的代理，您需要在代理注册表中手动注册。本文档介绍了如何在代理注册表中手动注册代理。

警告：us 和 eu 多区域位置不支持此功能。您必须使用受支持的区域或 global 位置。如需了解详情，请参阅 Agent Registry 位置。

准备工作

开始之前，请先设置代理注册表。您需要项目 ID 才能执行这些任务。

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

所需的角色

如需获得在代理注册表中手动注册代理所需的权限，请让管理员向您授予项目的以下 IAM 角色：

如需在 Agent Registry 中注册代理，请执行以下操作： Agent Registry API Editor (roles/agentregistry.editor)
对于跨项目注册，如需访问远程项目中的代理元数据： Agent Registry API Viewer (roles/agentregistry.viewer)

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

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

如果代理的端点或代理卡可通过标准公共网址访问，或者通过预配置的凭据进行身份验证，则您无需任何其他权限。

注册符合 A2A 标准的代理

如果您的远程代理实现了 Agent2Agent (A2A) 规范，请将代理注册表直接指向代理的 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 资源。使用 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 技能。

如果您想注册未实现 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。

注册其他项目中的代理

如果您的组织在多个 Google Cloud项目中部署了代理，并使用中央代理网关来管理出站流量，则可以将辐条项目或工作负载项目中的代理注册到中央代理注册表目录中。

由于自动注册仅发现在同一项目中创建的资源，因此您必须手动将每个远程代理注册到中央治理项目的注册表中。

跨项目注册的注意事项

在跨项目注册代理之前，请查看以下内容：

兼容的位置：Agent Registry 实例、Agent Gateway 和 Agent Endpoint 必须位于同一地理区域或 global 位置。
自动发现限制：不支持自动跨项目发现。您必须手动注册每个远程代理。
生命周期管理：当远程项目发生更改时，代理注册表中的手动条目不会自动更新或删除。当远程代理被修改或移除时，您必须在中央注册表中管理这些条目的生命周期。
仅限出站模式：使用代理网关的跨项目治理仅支持代理到任意位置（出站）网关。客户端到代理的入站网关要求代理和网关位于同一项目中。

注册远程代理

如需手动注册其他项目中的代理，请按以下步骤操作：

控制台

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

前往 Agent Registry
在项目选择器中，选择要注册代理的中央治理 Google Cloud项目。
选择代理标签页。
点击添加智能体。
在代理详情面板中，输入以下详细信息：
- 类型：如果远程代理实现了 A2A 协议，请选择 A2A；对于标准 REST 端点，请选择 Non-A2A。
- 区域：选择与您的中央网关和远程代理部署相匹配的区域。
提供代理端点：
- 对于 A2A 代理，请选择 From URI 并输入远程代理的代理卡片网址，或选择 Paste JSON 并粘贴 agent-card.json 内容。
- 对于非 A2A 代理，请输入远程代理的端点网址。
点击保存。

gcloud

A2A 代理：如需使用 gcloud CLI 从其他项目注册 A2A 代理，请在中央治理项目中运行以下命令：

gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@agent-card.json

REST 代理：如需注册来自其他项目的标准 REST 代理，请在中央治理项目中运行以下命令：

gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=REMOTE_ENDPOINT_URL,protocolBinding=PROTOCOL

替换以下内容：

AGENT_NAME：中央注册表中代理的名称，例如 remote-support-agent。
CENTRAL_PROJECT_ID：中央治理项目的项目 ID。
REGION：注册代理的区域。
DISPLAY_NAME：代理的人类可读名称，例如 Remote Support Agent。
REMOTE_ENDPOINT_URL：远程项目中运行的代理的端点网址，例如 https://<var>AGENT_SERVICE_NAME</var>-<var>HASH</var>.<var>REGION</var>.run.app。
PROTOCOL：端点的协议绑定。有效值为 http-json、grpc 或 jsonrpc。

Terraform

如需使用 Terraform 在中央治理项目中注册远程代理，请配置 google_agent_registry_service 资源并指定中央项目：

resource "google_agent_registry_service" "remote_agent" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Remote agent registered from project REMOTE_PROJECT_ID."

  agent_spec {
    type = "NO_SPEC"
  }

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

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.remote_agent.registry_resource
}

替换以下内容：

CENTRAL_PROJECT_ID：中央治理项目的项目 ID。
REGION：注册代理的区域。
AGENT_NAME：注册表中智能体的唯一名称，例如 remote-support-agent。
DISPLAY_NAME：代理的人类可读名称，例如 Remote Support Agent。
REMOTE_PROJECT_ID：代理托管到的项目 ID。
REMOTE_ENDPOINT_URL：在远程项目中运行的代理的端点网址。
PROTOCOL：端点的协议绑定。有效值为 HTTP_JSON、GRPC 或 JSONRPC。

验证注册

注册代理后，验证代理注册表是否已成功处理 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"

替换以下内容：

PROJECT_ID：项目 ID。
REGION：您要注册代理的区域。如果您不想使用特定区域，请使用值 global。
FILTER_EXPRESSION：要过滤的代理的过滤表达式。例如，如需按显示名称过滤，您可以使用 displayName='DISPLAY_NAME'。如需按全局唯一标识符 (URN) 进行过滤，您可以使用 agentId='urn:agent:AGENT_URN'。

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：智能体的直观易懂的显示名称。

后续步骤

了解如何管理注册代理。
了解自动注册，建议使用此方法注册部署到受管运行时环境的代理。

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

准备工作

所需的角色

注册符合 A2A 标准的代理

控制台

gcloud

Terraform

注册标准 REST 代理

控制台

gcloud

Terraform

注册其他项目中的代理

跨项目注册的注意事项

注册远程代理

控制台

gcloud

Terraform

验证注册

控制台

gcloud

Terraform

后续步骤

使用手动注册