身份和标识符

如需在 Agent Registry 中注册和管理代理，您需要跨四个架构层工作。每个层都使用特定的命名、身份或路由机制：

  • 注册数据库标识符（代理标识符、MCP 服务器标识符和端点标识符）：用于库存跟踪、注册数据库发现和过滤的逻辑性不可变统一资源名称 (URN)。这些 URN 不用于运行时治理。
  • 资源名称：注册时生成的标准全局唯一Google Cloud 资源名称（registryResource 或 name），供 Agent Gateway 路由规则、Identity-Aware Proxy (IAP) 出站政策以及 Identity and Access Management (IAM) 政策绑定使用。
  • 智能体主体：可验证的 IAM 身份，例如在Google Cloud 上运行的智能体的 SPIFFE ID 或外部智能体的服务账号，用于调用方身份验证、授权和审核日志记录。
  • 运行时引用：用于拓扑查询和出站流量匹配的计算或基础设施路径 (RuntimeReference)。

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

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

注册表标识符

注册表标识符是代理注册表分配给已注册组件的全局唯一且不可变的统一资源名称 (URN)。此 URN 为消费者和编排器代理提供了一个稳定的参考，以便在代理注册表中发现、过滤和搜索组件，无论底层基础设施迁移或代码更新如何，该 URN 始终保持不变。

注册表标识符是仅用于注册表发现和元数据注解的逻辑 URN。它们不同于运行时安全身份和资源名称，不能用于 IAM 政策绑定、授权标头或 Agent Gateway 路由规则。

代理注册表使用三种类型的注册表标识符：

代理标识符

代理注册表会为所有已注册的代理（包括 Google 管理的代理以及外部或自定义代理）分配代理标识符 (agentId)。如需管理智能体的安全通信和受政策约束的通信，请使用智能体的智能体主体，而不是智能体标识符。

代理注册表会在提取期间自动生成代理标识符。 确切的 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
  • 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 服务器上调用工具时，系统会使用调用代理主体来授权访问。

URN 格式取决于服务器是 Google 代管式服务还是外部注册的服务器：

  • Google 和 Google Cloud 远程 MCP 服务器： urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID
  • 手动注册的 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。

资源名称

在 Agent Registry 中注册代理、MCP 服务器或端点时，注册过程会生成一个标准 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

当您创建或检查可写入的 Service 资源时（例如，通过运行 gcloud agent-registry services describe），系统会在仅输出的 registryResource 字段中返回此资源名称。当您直接查询或检查生成的只读 Agent、McpServer 或 Endpoint 资源时（例如，使用 gcloud agent-registry agents describe 命令），系统会在标准 name 字段中返回此资源名称。

资源名称可用于绑定政策、路由网络流量和配置访问权限控制。下游治理界面（包括代理网关路由规则、IAP 出站政策和 IAM 资源政策）会根据此资源名称进行评估。它们不接受来自注册标识符（例如代理标识符、MCP 服务器标识符或端点标识符）的 URN。

如果您在政策绑定或路由规则中使用注册表标识符 URN 而不是资源名称，则 API 会返回 NOT_FOUND: Requested entity was not found. 错误。如果您在配置治理政策时遇到此错误，请验证以下内容：

  • 注册状态：确认目标代理、MCP 服务器或端点已在 Agent Registry 中注册，且位于预期位置。
  • 标识符格式：确认您的政策绑定或路由规则指定的是标准资源名称 (projects/PROJECT_NUMBER/locations/LOCATION/.../agentregistry-ID)，而不是注册标识符 URN。

智能体主体

智能体主体是 IAM 中智能体的安全身份。与用户或服务账号一样，代理使用其主账号来持有权限和调用下游服务。配置 IAM 政策时，您可以使用代理的主账号字符串来授予或限制访问权限。

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

  • 在 Google Cloud 基础设施上运行的智能体：对于托管运行时环境（例如 Gemini Enterprise Agent Platform 上的 Agent Runtime）， Google Cloud会自动预配格式为 SPIFFE ID 的托管 Workload Identity，该身份直接绑定到智能体的计算运行时。在 IAM 允许政策和绑定中引用此身份时，您必须使用 IAM 主体或主体集字符串格式，而不是 SPIFFE URI scheme。为 IAM 政策绑定使用 SPIFFE 字符串会返回 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 权限直接与代理的运行位置相关联。如果您在不同于代理部署位置的项目中注册代理，则运行时引用会指向托管底层工作负载的项目。

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

后续步骤