注册自定义 ADK 智能体

借助 Agent Registry，您可以注册使用智能体开发套件 (ADK) 构建并托管在您自己的基础架构上的自定义智能体，以便其他开发者和编排器智能体可以发现这些智能体。通过公开符合 Agent2Agent (A2A) 协议的智能体卡片并手动注册智能体的端点，您可以在 Agent Registry 中发现其 A2A 技能。

准备工作

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

所需的角色

如需获得在 Agent Registry 中注册自定义 ADK 智能体所需的权限，请让管理员为您授予已启用 Agent Registry 的治理项目的 Agent Registry API Editor (roles/agentregistry.editor) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

Agent Card 端点

为了让 Agent Registry 能够将自定义代理的功能编入索引，代理必须使用 Agent2Agent (A2A) protocol 公开其元数据和可用的 A2A 技能。

A2A 规范要求智能体在特定端点（通常为 /.well-known/agent-card.json）提供智能体卡片，即描述智能体身份和工具的 JSON 文档。

当您使用 ADK 的特定 A2A 服务器插件或模块注册智能体时，框架可以根据您在代码中提供的 Agent 定义和 tools 自动生成并提供此智能体卡片。

注册公开的智能体

将 ADK 智能体部署到托管环境并成功提供 REST 端点后，指示 Agent Registry 发现该智能体。

由于自定义部署需要手动注册，因此您需要在注册表中创建 Service 资源。将智能体生成的智能体卡片保存为本地 JSON 文件，例如 agent-card.json。

使用 gcloud CLI 通过 gcloud agent-registry services create 命令注册代理，确保指定 a2a-agent-card 规范类型，并使用 --agent-spec-content 标志上传本地文件：

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

规范文件的文件大小上限为 10 KB。

替换以下内容：

  • AGENT_NAME：您要为代理指定的名称，例如 my-custom-agent。
  • PROJECT_ID：项目 ID。
  • LOCATION：注册表位置或区域。
  • DISPLAY_NAME：代理的人类可读名称。

创建 Service 资源后，智能体注册表会解析智能体卡片，创建只读 Agent 资源，并为 ADK Python 代码中定义的 A2A 技能编制索引，以便其他开发者可以搜索这些技能。