身份和标识符

Agent Registry 会为已注册的智能体、MCP 服务器、端点和技能分配不同的标识符和身份，以便您发现功能、强制执行访问权限政策和路由运行时流量。了解每个标识符层的工作原理有助于您在整个 AI 生态系统中配置搜索查询、安全政策和网络路由。

架构层

Agent Registry 使用四个不同的层来识别、治理和路由已注册的组件：

  • 注册表标识符：逻辑、不可变的统一资源名称 (URN)，包括智能体标识符、MCP 服务器标识符、端点标识符和技能标识符，用于搜索、注册表发现和过滤。这些 URN 不用于运行时治理。
  • 资源名称：Agent Registry 分配给 Service、Agent、McpServer、Endpoint 和 Skill 资源的全球唯一标准Google Cloud 资源名称。下游服务（例如 Agent Gateway 路由规则、Identity-Aware Proxy [IAP] 出站流量政策和 Identity and Access Management [IAM] 政策绑定）使用 Agent、McpServer、Endpoint 和 Skill 资源的资源名称来强制执行治理政策。
  • 智能体主体：可验证的 IAM 身份，例如在Google Cloud 上运行的智能体的 SPIFFE ID 或外部智能体的服务账号，用于调用方身份验证、授权和审核日志记录。
  • 运行时引用：存储在 RuntimeReference 消息中并用于拓扑查询和出站流量匹配的计算或基础设施路径。

下表比较了每个层、其主要用途、下游治理角色和语法：

图层 主要目的 治理角色 语法
注册表标识符 稳定的注册表发现、元数据标记和搜索。 不可变，不用于治理。
  • 代理标识符：urn:agent:IDENTIFIER
  • MCP 服务器标识符：urn:mcp:IDENTIFIER
  • 端点标识符：urn:endpoint:IDENTIFIER
  • 技能标识符：urn:skill:IDENTIFIER
资源名称 用于强制执行政策的目标资源标识。 政策要求提供，并由 Agent Gateway 路由和 IAP 绑定使用。
  • 客服：projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID
  • MCP 服务器：projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID
  • 端点：projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID
  • 技能：projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID
智能体主体 调用方身份验证、授权和审核日志记录。 由 IAM 强制执行。
  • principal://PRINCIPAL_PATH
  • principalSet://PRINCIPAL_SET_PATH
运行时参考文档 物理计算路由和出站流量匹配。 在拓扑查询和 Agent Gateway 中进行评估，以匹配网络流量。 agentregistry.googleapis.com/system/RuntimeReference，其中包含计算或基础设施路径，如 uri: "RUNTIME_URI"

注册表标识符

注册表标识符是 Agent Registry 分配给已注册组件的全局唯一且不可变的统一资源名称 (URN)。此 URN 为使用者和编排器智能体提供了一个稳定的引用，用于在智能体注册表中发现、过滤和搜索组件，无论底层基础设施迁移或代码更新如何，该引用都保持不变。

Registry 标识符是逻辑 URN，专门用于 Registry 发现和元数据注解。它们与智能体主体和资源名称不同，不能用于 IAM 政策绑定、授权标头或 Agent Gateway 路由规则。

Agent Registry 使用四种类型的注册表标识符：

代理标识符

Agent Registry 会为所有已注册的代理（包括内置 Google 代理和自定义或外部代理）分配代理标识符 (agentId)。智能体标识符仅用于在 Agent Registry 中发现和过滤智能体，不用于 IAM 政策。如需在 IAM 政策中授予或限制智能体的访问权限，请使用其智能体主体。

智能体注册表会在提取期间自动生成智能体标识符。 确切的 URN 结构取决于部署代理的计算环境：

  • Gemini Enterprise Agent Platform 上的 Agent Runtime： urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID
  • Cloud Run 服务： urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME
  • Cloud Run 作业： urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME
  • Google Kubernetes Engine (GKE) 部署：urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:container:clusters:CLUSTER_NAME:k8s:namespaces:NAMESPACE:apps:deployments:DEPLOYMENT_NAME
  • Gemini Enterprise： urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:global:discoveryengine:collections:default_collection:engines:ENGINE_ID:assistants:default_assistant:agents:AGENT_ID
  • Google Workspace： urn:agent:googleapis.com:locations:global:workspaceagent:workspaceagent--a2a
  • 手动注册的代理： urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:AGENT_ID

MCP 服务器标识符

MCP 服务器标识符 (mcpServerId) 是一个注册表标识符，用于在 Agent Registry 中发现 MCP 服务器及其工具。

MCP 服务器仅响应请求，没有 IAM 主账号。当智能体调用 MCP 服务器上的工具时，系统会使用调用的智能体主体来授权访问。

以下是 MCP 服务器标识符的 URN 格式：

  • Google 和 Google Cloud 远程 MCP 服务器： urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID
  • Cloud Run 服务： urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME
  • GKE 部署：urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:container:clusters:CLUSTER_NAME:k8s:namespaces:NAMESPACE:apps:deployments:DEPLOYMENT_NAME
  • 手动注册的 MCP 服务器： urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID

端点标识符

端点标识符 (endpointId) 是分配给注册端点的注册表标识符，用于发现目标 API 目的地。

手动注册的端点的 URN 格式为 urn:endpoint:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:ENDPOINT_ID。

技能标识符

技能标识符 (skillId) 是分配给独立技能的注册表标识符，用于在 Agent Registry 中发现和解析技能包。

以下是技能标识符的 URN 格式，具体取决于技能的发布者：

  • 由 Google 管理的发布商： urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID
  • 不公开的发布商： urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-SKILL_ID

资源名称

无论是自动注册还是手动注册组件，Agent Registry 都会为生成的只读 Agent、McpServer 或 Endpoint 发现资源或 Skill 资源分配标准 Google Cloud 资源名称。每个资源名称在治理项目中都采用分层 URI 路径格式：

  • 代理： projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID
  • MCP 服务器： projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID
  • 端点： projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID

  • 技能： projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID

    对于手动注册的技能，SKILL_ID 包含 private- 前缀，例如 private-SKILL_ID。

    每个版本化技能修订版本都使用 projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID。

如果您配置了管理边界，则可以通过在请求中指定管理项目或成员项目来查询 Agent 或 McpServer 资源。Agent Registry 会保留其分配给组件的 ID（格式为 agentregistry-ID），并且您获取的资源名称会反映请求中指定的项目。因此，资源名称与您在查询中使用的项目相关联。不过，组件的注册表标识符及其运行时引用始终保留部署资源的成员项目，并且保持不可变。如需了解详情，请参阅跨管理边界的资源名称。

手动注册智能体、MCP 服务器或端点时，您会创建一个可写的 Service 资源，该资源会生成相应的只读 Agent、McpServer 或 Endpoint 资源。Service 资源有自己的资源名称：

projects/PROJECT_NUMBER/locations/LOCATION/services/SERVICE_ID

您可以查询只读资源和可写资源，以查看其资源名称。当您在终端中使用 gcloud agent-registry services describe 命令等查询 Service 资源时，输出还会显示 registryResource 字段，其中显示了相应只读 Agent、McpServer 或 Endpoint 资源的资源名称。如需了解详情，请参阅管理智能体、管理 MCP 服务器和工具、管理和发现端点以及管理技能。

资源名称可用于绑定政策、路由网络流量和配置访问权限控制。下游治理平台（包括 Agent Gateway 路由规则、IAP 出站流量政策和 IAM 资源政策）会根据此资源名称进行评估。请勿在政策绑定或路由规则中使用注册表标识符 URN。请改用资源名称。如需了解问题排查信息，请参阅管理 IAP 政策时出现“找不到资源实体”错误。

智能体主体

智能体主体是智能体在 IAM 中的身份。向智能体主体授予角色的方式与向用户或服务账号授予角色的方式相同，以便授予或限制访问权限。

在 Agent Registry 中，智能体如何被标识为主账号取决于其运行位置：

  • 在 Google Cloud 基础架构上运行的智能体：对于 Agent Runtime 等托管式运行时，Google Cloud 会自动预配格式为 SPIFFE ID 的托管式 Workload Identity，该身份直接绑定到智能体的计算运行时。在 IAM 允许政策和绑定中引用此身份时，您必须使用 IAM 主账号或主账号集字符串格式，而不是 SPIFFE URI scheme。将 SPIFFE 字符串用于 IAM 政策绑定会返回 INVALID_ARGUMENT 错误。
  • 在 Google Cloud外部运行的代理：外部或本地代理必须通过工作负载身份联合联合其外部身份，或使用标准服务账号与 Google Cloud 资源进行交互。身份验证完成后，该 Workload Identity 字符串或服务账号电子邮件地址将作为 IAM 政策中的智能体主体。

对于在 Google Cloud上运行的智能体，由于托管式智能体主体直接绑定到智能体运行时的计算资源，因此主体字符串会包含该底层计算资源的完整路径。

IAM 支持在以下范围内管理代理访问权限：

  • 单个引擎实例：向特定代理部署授予权限。例如，单个 Agent Runtime 实例通过单个主账号字符串表示：principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID
  • 项目范围：通过主账号集向在特定项目中运行的所有推理引擎授予权限：principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
  • 组织级范围：通过主账号集通配符向整个组织中的所有智能体授予权限：principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*

当您查看智能体的详细信息时，Agent Registry 会将各个智能体主体显示为仅输出属性。

运行时参考

运行时引用指向运行智能体、MCP 服务器或端点代码的底层计算基础设施。例如，运行时引用可以指向 Agent Runtime 推理引擎、GKE 部署或 Cloud Run 服务。

智能体的主账号字符串包含其运行时参考路径，该路径将 IAM 权限直接与智能体的运行位置相关联。如果您在与代理部署位置不同的治理项目中注册代理，或者跨管理边界发现代理，则运行时引用会指向底层工作负载运行所在的成员项目。

在代理注册表中，运行时引用由 agentregistry.googleapis.com/system/RuntimeReference 属性表示，该属性在其 uri 字段中包含计算或基础设施路径。您可以将此仅输出属性作为代理详细信息的一部分进行查看，也可以使用它在拓扑图中查询流量和关系。

后续步骤