Agent Registry 数据模型

Agent Registry 将您的 AI 生态系统整理为标准化资源，以便您在单个项目或管理边界内注册、发现和治理智能体、MCP 服务器、端点和技能。了解 Agent Registry 如何将可写 Service 资源与只读发现资源分开、如何跨项目限定资源范围，以及如何支持自动和手动注册，有助于您设计和管理注册表。

如需开始使用，请参阅设置智能体注册表。如需详细了解 Agent Registry API，请参阅 API 参考文档。

智能体组件

借助 Agent Registry，您可以注册、发现和治理以下类型的智能体组件：

  • 智能体：自主 AI 参与者，可执行特定任务、调用工具并与其他智能体协作。
  • MCP 服务器：实现 Model Context Protocol (MCP) 以公开标准化数据资源和工具的程序。工具是 MCP 服务器公开的确定性函数，智能体可以调用这些函数来执行特定操作。
  • 端点：智能体访问的目标网址，通常是 REST API。通过将这些目标抽象为可管理的资源，Agent Registry 可让您集中管理智能体可以访问的外部 API。
  • 技能：可扩展智能体功能的模块化功能。独立技能是直接在注册表中管理的指令和可选脚本包。A2A 技能是智能体卡片上的功能描述，用于告知其他智能体何时以及如何与其通信。如需了解详情，请参阅技能架构。

服务资源和发现资源

Agent Registry 表示组件的方式取决于其组件类型和注册模型。如需详细了解组件生命周期和发现，请参阅组件生命周期和发现。

智能体、MCP 服务器和端点

无论是自动注册还是手动注册，Agent Registry 都会将代理、MCP 服务器或端点表示为只读 Agent、McpServer 或 Endpoint 发现资源。使用者（例如编排器代理、客户端应用和开发者）可以使用这些发现资源来列出、搜索和查看已注册的组件。

对于自动注册的组件，Agent Registry 会直接从支持的运行时中提取元数据，并创建发现资源，而无需 Service 资源。

当您手动注册智能体、MCP 服务器或端点时，Agent Registry 会通过创建以下项，将管理操作与组件发现分离开来：

  • 可写 Service 资源：存储组件的元数据，包括智能体组件的类型、其接口网址、说明、协议绑定和功能规范。您可以创建、更新或删除 Service 资源以执行管理操作（例如更新元数据或取消注册组件），而无需修改或删除底层部署。
  • 发现资源：当您创建或更新 Service 资源时，Agent Registry 会读取元数据，并自动创建或更新 Agent、McpServer 或 Endpoint 发现资源，以表示注册表中的组件。

您在创建 Service 资源时使用的规范标志决定了生成的只读资源集合：

标志 资源集合 使用场景 有效值
--agent-spec-type
--agent-spec-content		 agents 集合中的 Agent 资源 远程 A2A 兼容或标准 REST 智能体 a2a-agent-card，no-spec
--endpoint-spec-type
--endpoint-spec-content		 endpoints 集合中的 Endpoint 资源 外部目标 REST API 或服务网址 no-spec
--mcp-server-spec-type
--mcp-server-spec-content		 mcp-servers 集合中的 McpServer 资源 外部 Model Context Protocol (MCP) 服务器 tool-spec，no-spec

这些标志对是互斥的；指定多个标志对中的标志会返回错误。如果您为错误的组件类型指定了标志对，Agent Registry 会在与您指定的标志匹配的集合中创建发现资源。例如，在注册端点时传递 --agent-spec-type=no-spec 会创建 Agent 资源，而不是 Endpoint 资源，因此特定于类型的查询和治理政策不会按预期应用。

独立技能

独立技能不使用单独的 Service 资源。而是直接使用顶级 Skill 资源、子 SkillRevision 资源和 Publisher 资源来注册、版本化和查询技能。

在技能扫描期间检测到的安全问题会作为只读 Finding 资源公开。如需了解详情，请参阅扫描技能是否存在安全问题。

跨项目数据模型

配置管理边界后，Agent Registry 会从管理项目中集中发现和治理所有成员项目。

当您从管理项目查询、列出或搜索资源时，Agent Registry 会应用以下范围限定规则，以提供整合的目录，而不会重复资源或造成端点冲突：

资源类别 管理边界中的范围 说明
自动发现的资源 从成员项目汇总 当您在管理项目的某个位置列出或搜索成员项目中自动发现的智能体和 MCP 服务器时，这些智能体和 MCP 服务器会汇总到管理项目视图中。查看、列出或搜索代理或 MCP 服务器时，您可以在请求中指定管理项目 ID 或成员项目 ID。资源名称会保留 Agent Registry 分配给组件的 ID，并使用请求中指定的项目。
手动注册的资源 范围限定为在其中创建它们的项目 手动注册为 Service 资源的自定义智能体、外部 MCP 服务器和端点仅限于其创建所在的项目。在管理项目中创建这些资源，使其在管理边界内可见；或在成员项目中创建这些资源，使其仅在该单个项目中可见。
绑定关系 范围限定为在其中创建它们的项目 Binding 资源的范围限定为创建这些资源的项目。在管理项目中创建它们，以便在整个边界内可见；或在成员项目中创建它们，以便在单个项目中可见。
独立技能和发布商 范围限定为在其中创建它们的项目 自定义独立 Skill、SkillRevision、Publisher 和 Finding 资源的作用域限定为创建这些资源的项目，并且不会从成员项目汇总到管理项目。设置 Agent Registry 后，系统会自动在所有项目中发现 Google 管理的独立技能。
AI 应用 范围限定为在其中创建它们的项目 只读 AiApplication 资源及其关联的组件视图的作用域限定为创建应用的项目和位置。

支持的产品和组件

Agent Registry 会根据支持的产品和组件的注册方式（自动或手动）对其进行分类。

自动注册

Agent Registry 会自动发现并提取在您的项目中或管理边界内的成员项目中部署的受支持Google Cloud 工作负载。对于实现开放式 Agent2Agent (A2A) 协议的代理，注册表会自动从其代理卡片中提取其 A2A 技能和功能。在设置代理注册表时，Google 管理的独立技能也可以在所有项目中被发现。

下表列出了 Agent Registry 自动注册的产品和组件：

组件类型 支持的产品
代理
MCP 服务器
skill Google 管理的 skill 可从所有项目中发现

手动注册

远程组件是指托管在治理项目或管理边界之外的智能体、MCP 服务器或端点，例如托管在没有边界的单独 Google Cloud 项目中、本地基础设施中或外部云中。您可以使用 Service 资源在治理项目中手动注册这些远程组件。您还可以使用 Service 资源在不受支持的运行时上手动注册组件，或为未实现 A2A protocol 的代理手动注册组件。对于自定义独立技能，您可以使用 Skill 资源。

下表列出了您手动注册的产品和组件：

组件类型 支持的资源
代理 部署在 Compute Engine、GKE、Cloud Run、本地系统或外部云上的远程代理
MCP 服务器 在不受支持的运行时或外部 MCP 服务器上自定义智能体组件
Endpoints 作为端点进行治理的外部目标 REST API 或服务网址
skill 由贵组织编写的独立技能

后续步骤