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

为代理使用手动注册

借助智能体注册表，您可以手动注册符合 A2A 标准和标准 REST 智能体，这些智能体托管在 Google Cloud外部、在不受支持的运行时上运行，或部署在不同的 Google Cloud 项目中。通过为这些智能体创建 Service 资源，您可以在整个 AI 生态系统中发现其端点和功能。

Agent Registry 使用一个中央 Google Cloud 治理项目。在本文档中，术语“远程”是指托管在治理项目之外（例如在单独的 Google Cloud 项目、本地环境或外部云中）或在不受支持的运行时上运行的代理。由于自动注册只会发现部署在启用了 Agent Registry 的治理项目中的受支持资源，因此您必须手动将远程代理注册到治理项目的注册表中。

代理类型和限制

您可以手动注册两种类型的代理：

符合 A2A 标准的代理：使用 A2A_AGENT_CARD 类型实现 Agent2Agent (A2A) 规范的代理。注册表会扫描其 agent-card.json 智能体卡片端点，以将其 A2A 技能编入索引。
标准 REST 代理：不实现 A2A 规范并使用 NO_SPEC 类型的远程代理，例如公开 REST API 端点的代理。

us 和 eu 多区域位置不支持手动注册；您必须使用受支持的国家/地区或 global 位置。如需了解详情，请参阅 Agent Registry 位置。

准备工作

设置 Agent Registry。
获取已启用 Agent Registry 的治理项目的项目 ID。
如需使用本文档中的 Google Cloud CLI 命令，请设置 gcloud CLI 环境。

所需的角色

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

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

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

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

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

注册符合 A2A 标准的代理

如果您的远程代理实现了 A2A 规范，请将 Agent Registry 定向到代理的 agent-card.json 载荷。注册表会自动同步智能体卡片，并为智能体的可用 A2A 技能编制索引，以便于发现。

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

控制台

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

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

gcloud

您使用的规范标志决定了组件所属的资源集合。如需查看标志与资源集合的完整映射，请参阅 [服务资源和发现资源](/agent-registry/data-model#service-resources)。

如需注册 A2A 智能体，请将智能体的智能体卡片保存为本地 JSON 文件（例如 agent-card.json），然后运行 gcloud agent-registry services create 命令：

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：您要为代理指定的 ID，例如 my-support-agent。ID 必须包含 4 到 63 个字符，并且只能包含小写字母、数字和连字符。
PROJECT_ID：项目 ID。
REGION：您要在其中注册代理的区域。如果您不想使用特定区域，请使用值 global。
DISPLAY_NAME：您要为智能体指定的人类可读名称，例如 Support Agent。

Terraform

您配置的规范块决定了组件所属的资源集合。如需查看规范与资源集合的完整映射，请参阅 [服务资源和发现资源](/agent-registry/data-model#service-resources)。

如需注册符合 A2A 标准的代理，请配置 google_agent_registry_service 资源。指定 agent_spec 块，其中 A2A_AGENT_CARD 类型和 content 表示智能体卡片 JSON 载荷：

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({
      name               = "AGENT_NAME"
      description        = "A custom support agent registered using Terraform."
      version            = "1.0.0"
      capabilities       = {}
      defaultInputModes  = ["text/plain"]
      defaultOutputModes = ["text/plain"]
      supportedInterfaces = [
        {
          url             = "https://api.example.com/v1/agents/support"
          protocolBinding = "JSONRPC"
          protocolVersion = "1.0"
        }
      ]
      skills = [
        {
          id          = "customer_lookup"
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
          tags        = ["support", "customer"]
        }
      ]
    })
  }
}

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

替换以下内容：

REGION：您注册代理的区域。
AGENT_NAME：您要为代理指定的唯一 ID，例如 my-support-agent。ID 必须包含 4 到 63 个字符，并且只能包含小写字母、数字和连字符。
DISPLAY_NAME：您要为智能体指定的人类可读名称，例如 Support Agent。

注册标准 REST 智能体

标准 REST 代理可通过名称和说明被发现，但除非采用 A2A 协议，否则不具备可搜索的 A2A 技能。

如需注册未实现 A2A 规范的远程代理，请创建非 A2A Service 资源。Agent Registry 会在 agents 集合中为非 A2A 智能体生成一个只读 Agent 资源，包括其端点网址，以便编排器、其他智能体和 Agent Gateway 能够发现并连接到该智能体。

在 Google Cloud 控制台中将代理类型设置为非 A2A，或在 gcloud CLI 命令中使用 --agent-spec-type=no-spec 标志，即可注册 AI 智能体。请勿将该代理单独注册为 Endpoint 资源。仅当您想要管理代理与非代理 REST API 或 Web 服务（例如数据库 API、第三方 SaaS API 或 Google API）的出站连接时，才注册 Endpoint 资源。如需了解如何注册非代理 API 目标，请参阅注册端点。

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

控制台

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

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

gcloud

如需注册标准 REST 代理并指定托管代理的端点网址，请运行 gcloud agent-registry services create 命令，并指定 --agent-spec-type=no-spec 和 --interfaces 标志：

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：您要为代理指定的 ID，例如 my-remote-rest-agent。ID 必须包含 4 到 63 个字符，并且只能包含小写字母、数字和连字符。
PROJECT_ID：项目 ID。
REGION：注册表区域。
DISPLAY_NAME：您要为智能体指定的人类可读名称，例如 Remote REST Agent。
ENDPOINT_URL：代理的 API 端点网址，例如 https://api.example.com/v1/agents/1234。
PROTOCOL：端点的协议绑定。有效值为 http-json、grpc 或 jsonrpc。

Terraform

您配置的规范块决定了组件所属的资源集合。如需查看规范与资源集合的完整映射，请参阅 [服务资源和发现资源](/agent-registry/data-model#service-resources)。

如需注册标准 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：您要为代理指定的唯一 ID，例如 my-remote-rest-agent。ID 必须包含 4 到 63 个字符，并且只能包含小写字母、数字和连字符。
DISPLAY_NAME：您要为智能体指定的人类可读名称，例如 Remote REST Agent。
ENDPOINT_URL：代理的 API 端点网址，例如 https://api.example.com/v1/agents/1234。
PROTOCOL：端点的协议绑定。有效值为 HTTP_JSON、GRPC 或 JSONRPC。

注册其他项目中的智能体

如果您的组织在多个 Google Cloud 项目中部署智能体，并使用中央智能体网关（在“智能体到任何位置”出站流量模式下）来管理流量，则您必须手动将这些其他 Google Cloud 项目中的每个远程智能体注册到中央治理项目的注册表中。如需详细了解此架构，请参阅示例部署模式。

跨项目注册的注意事项

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

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

注册远程代理

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

控制台

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

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

gcloud

A2A 智能体：如需注册其他项目中的 A2A 智能体，请运行 gcloud agent-registry services create 命令：

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 命令：

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：代理在中央注册表中的 ID，例如 remote-support-agent。ID 必须为 4 到 63 个字符，并且只能包含小写字母、数字和连字符。
CENTRAL_PROJECT_ID：中央治理项目的项目 ID。
REGION：您注册代理以及中央网关和远程代理所在的区域，例如 us-central1。
DISPLAY_NAME：代理的人类可读名称，例如 Remote Support Agent。
REMOTE_ENDPOINT_URL：在另一个 Google Cloud 项目中运行的远程代理的端点网址，例如 https://remote-support-agent-abc123.us-central1.run.app 或 https://api.example.com/v1/agents/support。
PROTOCOL：端点的协议绑定。有效值为 http-json、grpc 或 jsonrpc。

Terraform

您配置的规范块决定了组件所属的资源集合。如需查看规范与资源集合的完整映射，请参阅 [服务资源和发现资源](/agent-registry/data-model#service-resources)。

如需使用 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 AGENT_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：您注册代理以及中央网关和远程代理所在的区域，例如 us-central1。
AGENT_NAME：代理在注册表中的唯一 ID，例如 remote-support-agent。ID 必须包含 4 到 63 个字符，并且只能包含小写字母、数字和连字符。
DISPLAY_NAME：代理的人类可读名称，例如 Remote Support Agent。
AGENT_PROJECT_ID：托管远程代理的单独 Google Cloud 项目的项目 ID。
REMOTE_ENDPOINT_URL：在另一个 Google Cloud 项目中运行的远程代理的端点网址，例如 https://remote-support-agent-abc123.us-central1.run.app 或 https://api.example.com/v1/agents/support。
PROTOCOL：端点的协议绑定。有效值为 HTTP_JSON、GRPC 或 JSONRPC。

验证注册

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

控制台

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

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

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

gcloud

使用 gcloud agent-registry agents list 命令列出注册表中的已注册智能体：

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

后续步骤

为代理使用手动注册