Identidad e identificadores

Para registrar y administrar agentes en Agent Registry, debes trabajar en cuatro capas arquitectónicas. Cada capa usa un mecanismo específico de nomenclatura, identidad o enrutamiento:

  • Identificadores de registro (identificadores de agentes, identificadores de servidores de MCP y identificadores de extremos): Son nombres de recursos uniformes (URN) lógicos e inmutables que se usan para el seguimiento del inventario, el descubrimiento del registro y el filtrado. Estos URN no se usan para la administración del tiempo de ejecución.
  • Nombres de recursos: Nombres de recursosGoogle Cloudestándar y únicos a nivel global (registryResource o name) que se generan durante el registro y que usan las reglas de enrutamiento de Agent Gateway, las políticas de salida de Identity-Aware Proxy (IAP) y las vinculaciones de políticas de Identity and Access Management (IAM).
  • Principales del agente: Son identidades de IAM verificables, como IDs de SPIFFE para agentes que se ejecutan enGoogle Cloud o cuentas de servicio para agentes externos, que se usan para la autenticación, la autorización y el registro de auditoría del llamador.
  • Referencias de tiempo de ejecución: Son las rutas de infraestructura o de procesamiento (RuntimeReference) que se usan para las consultas de topología y la correlación del tráfico de salida.

En la siguiente tabla, se comparan cada capa, su propósito principal, su rol de administración posterior y su sintaxis:

Capa Propósito principal Rol de administración Sintaxis
Identificadores de registro
(identificadores de agente, servidor de MCP o extremo)		 Descubrimiento, etiquetado de metadatos y búsqueda estables en el registro Es inmutable y no se usa para la administración.
  • urn:agent:IDENTIFIER
  • urn:mcp:IDENTIFIER
  • urn:endpoint:IDENTIFIER
Nombre del recurso Identificación del recurso de destino para la aplicación de la política. Lo requieren las políticas y lo usan las rutas de Agent Gateway y las vinculaciones de 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
Agente principal Autenticación, autorización y registro de auditoría de la entidad que llama. IAM aplica esta política.
  • principal://PRINCIPAL_PATH
  • principalSet://PRINCIPAL_SET_PATH
Referencia del entorno de ejecución Enrutamiento de procesamiento físico y coincidencia de tráfico saliente. Se evalúa en las consultas de topología y en Agent Gateway para que coincida con el tráfico de red. agentregistry.googleapis.com/system/RuntimeReference que contiene la ruta de acceso de procesamiento o infraestructura como uri: "RUNTIME_URI"

Identificadores de registro

Un identificador de registro es un nombre de recurso uniforme (URN) inmutable y único a nivel global que Agent Registry asigna a un componente registrado. Este URN proporciona una referencia estable para que los consumidores y los agentes de orquestación descubran, filtren y busquen componentes en el Registro de agentes, y permanece constante independientemente de las migraciones de infraestructura subyacentes o las actualizaciones de código.

Los identificadores de registro son URN lógicas que se usan exclusivamente para el descubrimiento de registros y la anotación de metadatos. Difieren de las identidades de seguridad del entorno de ejecución y los nombres de recursos, y no se pueden usar en vinculaciones de políticas de IAM, encabezados de autorización ni reglas de enrutamiento de Agent Gateway.

El Registro de agentes usa tres tipos de identificadores de registro:

Identificadores de agentes

Agent Registry asigna un identificador de agente (agentId) a todos los agentes registrados, incluidos los agentes administrados por Google y los agentes externos o personalizados. Para administrar la comunicación segura y regida por políticas de un agente, usa su entidad principal del agente en lugar de su identificador de agente.

El Registro de agentes genera automáticamente identificadores de agentes durante la transferencia. La estructura exacta del URN depende del entorno de procesamiento en el que se implementa el agente:

  • Agent Runtime en Gemini Enterprise Agent Platform: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID
  • Servicios de Cloud Run: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME
  • Trabajos de Cloud Run: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME
  • Implementaciones de 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
  • Agentes registrados manualmente: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:AGENT_ID

Identificadores del servidor de MCP

Un identificador de servidor de MCP (mcpServerId) es un identificador de registro que se usa para descubrir un servidor de MCP y sus herramientas en Agent Registry.

Los servidores de MCP solo responden a las solicitudes y no tienen un principal de IAM. Cuando un agente invoca herramientas en un servidor de MCP, el acceso se autoriza con el principal del agente que realiza la llamada.

El formato del URN depende de si el servidor es un servicio administrado por Google o un servidor externo registrado:

  • Servidores de MCP remotos y de Google Cloud Google: urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID
  • Servidores de MCP registrados de forma manual: urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID

Identificadores de extremos

Un identificador de extremo (endpointId) es un identificador de registro asignado a un extremo registrado para descubrir destinos de API objetivo.

El formato de URN para los extremos registrados manualmente es urn:endpoint:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:ENDPOINT_ID.

Nombres de recursos

Cuando registras un agente, un servidor de MCP o un extremo en Agent Registry, el proceso de registro genera un nombre de recurso estándar Google Cloudcon el formato de una ruta de URI jerárquica:

  • Agentes: projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID
  • Servidores de MCP: projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID
  • Endpoints: projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID

Cuando creas o inspeccionas un recurso Service grabable, por ejemplo, ejecutando gcloud agent-registry services describe, este nombre de recurso se devuelve en el campo registryResource de solo salida. Cuando consultas o inspeccionas el recurso Agent, McpServer o Endpoint de solo lectura resultante directamente, por ejemplo, con el comando gcloud agent-registry agents describe, este nombre de recurso se devuelve en el campo name estándar.

Los nombres de recursos se pueden usar para vincular políticas, enrutar el tráfico de red y configurar controles de acceso. Las plataformas de administración descendentes, incluidas las reglas de enrutamiento de Agent Gateway, las políticas de salida de IAP y las políticas de recursos de IAM, se evalúan en función de este nombre de recurso. No aceptan URN de identificadores de registro, como identificadores de agentes, identificadores de servidores de MCP o identificadores de extremos.

Si usas un URN de identificador de registro en una vinculación de política o una regla de enrutamiento en lugar del nombre del recurso, la API devolverá un error NOT_FOUND: Requested entity was not found.. Si encuentras este error cuando configuras políticas de administración, verifica lo siguiente:

  • Estado del registro: Confirma que el agente, el servidor de MCP o el extremo de destino estén registrados en Agent Registry en la ubicación esperada.
  • Formato del identificador: Confirma que tu vinculación de política o regla de enrutamiento especifique el nombre de recurso estándar (projects/PROJECT_NUMBER/locations/LOCATION/.../agentregistry-ID) en lugar del URN del identificador de registro.

Principales del agente

Una principal del agente es la identidad de seguridad de un agente en IAM. Al igual que una cuenta de usuario o de servicio, un agente usa su principal para tener permisos y llamar a servicios descendentes. Cuando configuras políticas de IAM, usas la cadena principal del agente para otorgar o restringir el acceso.

En Agent Registry, la forma en que se identifica a un agente como principal depende de dónde se ejecute:

  • Agentes que se ejecutan en la infraestructura Google Cloud : Para los tiempos de ejecución administrados, como Agent Runtime en Gemini Enterprise Agent Platform, Google Cloudse aprovisiona automáticamente una Workload Identity administrada con el formato de un ID de SPIFFE, que se vincula directamente al tiempo de ejecución de cómputo del agente. Cuando hagas referencia a esta identidad en las vinculaciones y políticas de IAM de permiso, debes usar el formato de cadena del principal de IAM o del conjunto de principales en lugar del esquema de URI de SPIFFE. Si se usa una cadena de SPIFFE para una vinculación de política de IAM, se devuelve un error INVALID_ARGUMENT.
  • Agentes que se ejecutan fuera de Google Cloud: Los agentes externos o locales deben federar su identidad externa a través de la federación de identidades para cargas de trabajo o usar una cuenta de servicio estándar para interactuar con los recursos de Google Cloud . Una vez autenticada, esa cadena de identidad de Workload Identity federada o el correo electrónico de la cuenta de servicio actúan como principal del agente en las políticas de IAM.

En el caso de los agentes que se ejecutan en Google Cloud, dado que el principal del agente administrado está vinculado directamente al recurso de cómputo del entorno de ejecución del agente, la cadena del principal incorpora la ruta completa a ese recurso de cómputo subyacente.

IAM admite el control del acceso de los agentes en los siguientes alcances:

  • Instancia de un solo motor: Otorga permisos a una implementación de agente específica. Por ejemplo, una instancia individual de Agent Runtime se representa a través de una sola cadena principal: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID
  • Alcance del proyecto: Otorga permisos a todos los motores de razonamiento que se ejecutan dentro de un proyecto específico a través de un conjunto de entidades: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
  • Alcance en toda la organización: Otorga permisos a todos los agentes de toda la organización a través de un comodín de conjunto de principales: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*

El registro de agentes muestra el principal del agente individual como un atributo de solo salida cuando consultas los detalles de un agente.

Referencias de tiempo de ejecución

Una referencia de entorno de ejecución apunta a la infraestructura de procesamiento subyacente en la que se ejecuta el código de un agente, un servidor de MCP o un extremo. Por ejemplo, una referencia de tiempo de ejecución puede apuntar a un motor de razonamiento de Agent Runtime, una implementación de GKE o un servicio de Cloud Run.

La cadena principal de un agente incluye su ruta de referencia del entorno de ejecución, que vincula los permisos de IAM directamente al lugar donde se ejecuta el agente. Si registras un agente en un proyecto diferente de aquel en el que se implementa, la referencia de tiempo de ejecución apunta al proyecto que aloja la carga de trabajo subyacente.

En la API de Agent Registry, la referencia de tiempo de ejecución se representa con el atributo agentregistry.googleapis.com/system/RuntimeReference, que contiene la ruta de acceso de infraestructura o procesamiento en su campo uri. Puedes ver este atributo de solo salida como parte de los detalles del agente o usarlo para consultar los flujos de tráfico y las relaciones en el gráfico de topología.

¿Qué sigue?