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

使用手动注册

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

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

准备工作

开始之前，请先设置 Agent Registry。您需要项目 ID 才能执行这些任务。

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

所需角色

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

如需在 Agent Registry 中注册代理，请授予 Agent Registry API Editor (roles/agentregistry.editor)
如需进行跨项目注册，请授予 Agent Registry API Viewer 角色 (roles/agentregistry.viewer)，以便访问远程项目中的代理元数据

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

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

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

注册符合 A2A 标准的代理

如果您的远程代理实现了 Agent2Agent (A2A) 规范，请将 Agent Registry 指向代理的 agent-card.json 载荷。注册表会自动同步代理卡片，并为发现功能编入代理的可用 A2A 技能的索引。

请按照以下步骤注册代理：

控制台

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

前往 Agent Registry
在项目选择器中，选择您在其中设置 Agent Registry的 Google Cloud 项目。
选择 Agents （代理）标签页。
点击添加智能体 。
在代理详细信息 面板中，输入以下详细信息：
- 类型：选择 A2A。
- 区域：选择您要在其中注册代理的地理位置。
请从下列选项中选择一项：
- 如需使用代理的资源 URI 注册代理，请选择 From URI （从 URI）标签页，然后在 URI 字段中输入有效网址。然后，点击导入以从网址获取代理卡片。
- 如需复制并粘贴代理卡片内容，请选择 Paste JSON （粘贴 JSON）标签页，然后粘贴 agent-card.json 文件的完整内容。
点击保存。

gcloud

您使用的规范标志决定了您的服务所属的资源集合。如需查看标志与资源集合的完整映射，请参阅 API 资源。

如需注册 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

您配置的规范块（例如 agent_spec）决定了您的服务所属的资源集合。如需查看规范与资源集合的完整映射，请参阅 API 资源。

如需注册符合 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 规范的远程代理，Agent Registry API 会使用 --agent-spec-type=no-spec 创建 Service 资源。

如需注册外部 API 目标或工具端点而不是代理，请参阅注册端点。

请按照以下步骤注册代理：

控制台

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

前往 Agent Registry
在项目选择器中，选择您在其中设置 Agent Registry的 Google Cloud 项目。
选择 Agents （代理）标签页。
点击添加智能体 。
在代理详细信息 面板中，输入以下详细信息：
- 类型：选择 Non-A2A。
- 名称：输入代理的简单易懂的显示名称，例如 Travel Agent。
- 说明：输入代理的功能说明，例如 A test agent that plans travel itineraries.
- 区域：选择您要在其中注册代理的地理位置。
- 端点：输入代理的托管端点。
点击保存。

gcloud

您使用的规范标志决定了您的服务所属的资源集合。如需查看标志与资源集合的完整映射，请参阅 API 资源。

您可以选择使用 --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

您配置的规范块（例如 agent_spec）决定了您的服务所属的资源集合。如需查看规范与资源集合的完整映射，请参阅 API 资源。

如需注册标准 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 Gateway 来管理出站流量，则您可以将来自 spoke 项目或工作负载项目的代理注册到中央 Agent Registry 目录中。

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

跨项目注册的注意事项

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

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

注册远程代理

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

控制台

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

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

gcloud

您使用的规范标志决定了您的服务所属的资源集合。如需查看标志与资源集合的完整映射，请参阅 API 资源。

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

您配置的规范块（例如 agent_spec）决定了您的服务所属的资源集合。如需查看规范与资源集合的完整映射，请参阅 API 资源。

如需使用 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。

验证注册

注册代理后，请验证 Agent Registry 是否已成功处理 Service 并创建相应的 Agent 资源：

控制台

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

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

该页面会显示所有已注册代理及其详细信息的列表。

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

后续步骤

使用手动注册