Identidade e identificadores

Para registrar e gerenciar agentes no Agent Registry, você trabalha em quatro camadas arquitetônicas. Cada camada usa um mecanismo específico de nomenclatura, identidade ou roteamento:

A tabela a seguir compara cada camada, a finalidade principal, a função de governança downstream e a sintaxe:

Camada Finalidade principal Função de governança Sintaxe
Identificadores de registro
(identificadores de agente, servidor MCP ou endpoint)		 Descoberta, inclusão de tag de metadados e pesquisa de registros estáveis. Imutável e não usado para governança.
  • urn:agent:IDENTIFIER
  • urn:mcp:IDENTIFIER
  • urn:endpoint:IDENTIFIER
Nome do recurso Identificação do recurso de destino para aplicação da política. Exigido pelas políticas e usado pelas rotas do Gateway de Agente e vinculações do 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
Principal do agente Autenticação, autorização e geração de registros de auditoria do caller. Aplicado pelo IAM.
  • principal://PRINCIPAL_PATH
  • principalSet://PRINCIPAL_SET_PATH
Referência de tempo de execução Roteamento de computação física e correspondência de tráfego de saída. Avaliado em consultas de topologia e no Gateway de Agente para corresponder ao tráfego de rede. agentregistry.googleapis.com/system/RuntimeReference que contém o caminho de computação ou infraestrutura como uri: "RUNTIME_URI"

Identificadores de registro

Um identificador de registro é um nome uniforme de recurso (URN) globalmente exclusivo e imutável que o Agent Registry atribui a um componente registrado. Esse URN fornece uma referência estável para que consumidores e agentes orquestradores descubram, filtrem e pesquisem componentes no Agent Registry, permanecendo constante independente de migrações de infraestrutura ou atualizações de código.

Os identificadores de registro são URNs lógicos usados exclusivamente para descoberta de registro e anotação de metadados. Elas são diferentes das identidades de segurança de tempo de execução e dos nomes de recursos e não podem ser usadas em vinculações de políticas do IAM, cabeçalhos de autorização ou regras de rota do gateway de agentes.

O Agent Registry usa três tipos de identificadores de registro:

Identificadores de agente

O Agent Registry atribui um identificador de agente (agentId) a todos os agentes registrados, incluindo agentes gerenciados pelo Google e agentes externos ou personalizados. Para gerenciar a comunicação segura e regida por políticas de um agente, use o principal do agente em vez do identificador dele.

O Agent Registry gera automaticamente identificadores de agentes durante a transferência. A estrutura exata do URN depende do ambiente de computação em que o agente é implantado:

  • Ambiente de execução do agente na Gemini Enterprise Agent Platform: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID
  • Serviços do Cloud Run: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME
  • Jobs do Cloud Run: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME
  • Implantações do 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 do servidor MCP

Um identificador de servidor MCP (mcpServerId) é um identificador de registro usado para descobrir um servidor MCP e as ferramentas dele no Agent Registry.

Os servidores MCP só respondem a solicitações e não têm um principal do IAM. Quando um agente invoca ferramentas em um servidor MCP, o acesso é autorizado usando o principal do agente de chamada.

O formato do URN depende de o servidor ser um serviço gerenciado pelo Google ou um servidor externo registrado:

  • Servidores MCP remotos do Google e Google Cloud : urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID
  • Servidores MCP registrados manualmente: urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID

Identificadores de endpoint

Um identificador de endpoint (endpointId) é um identificador de registro atribuído a um endpoint registrado para descobrir destinos de API de destino.

O formato URN para endpoints registrados manualmente é urn:endpoint:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:ENDPOINT_ID.

Nomes de recursos

Quando você registra um agente, um servidor MCP ou um endpoint no Agent Registry, o processo de registro gera um nome de recurso Google Cloudpadrão formatado como um caminho de URI hierárquico:

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

Ao criar ou inspecionar um recurso Service gravável, por exemplo, ao executar gcloud agent-registry services describe, esse nome de recurso é retornado no campo somente saída registryResource. Quando você consulta ou inspeciona o recurso somente leitura Agent, McpServer ou Endpoint diretamente, por exemplo, usando o comando gcloud agent-registry agents describe, esse nome de recurso é retornado no campo padrão name.

Os nomes de recursos podem ser usados para vincular políticas, rotear o tráfego de rede e configurar controles de acesso. As governanças downstream, incluindo regras de rota do Gateway de Agente, políticas de saída do IAP e políticas de recursos do IAM, são avaliadas em relação a esse nome de recurso. Eles não aceitam URNs de identificadores de registro, como identificadores de agente, identificadores de servidor MCP ou identificadores de endpoint.

Se você usar um URN identificador de registro em uma vinculação de política ou regra de rota em vez do nome do recurso, a API vai retornar um erro NOT_FOUND: Requested entity was not found.. Se você encontrar esse erro ao configurar políticas de governança, verifique o seguinte:

  • Status do registro: confirme se o agente, o servidor MCP ou o endpoint de destino está registrado no Agent Registry no local esperado.
  • Formato do identificador: confirme se a vinculação de política ou a regra de rota especifica o nome padrão do recurso (projects/PROJECT_NUMBER/locations/LOCATION/.../agentregistry-ID) em vez do URN do identificador do registro.

Principais do agente

Um principal de agente é a identidade de segurança de um agente no IAM. Assim como um usuário ou uma conta de serviço, um agente usa o principal dele para manter permissões e chamar serviços downstream. Ao configurar políticas do IAM, você usa a string principal do agente para conceder ou restringir o acesso.

No Agent Registry, a forma como um agente é identificado como principal depende de onde ele é executado:

  • Agentes executados na Google Cloud infraestrutura: para ambientes de execução gerenciados, como o Agent Runtime na Gemini Enterprise Agent Platform, o Google Cloudprovisiona automaticamente uma identidade de carga de trabalho gerenciada formatada como um ID do SPIFFE, que é vinculada diretamente ao ambiente de execução de computação do agente. Ao referenciar essa identidade em políticas e vinculações de permissão do IAM, use o formato de string principal do IAM ou conjunto principal em vez do esquema de URI do SPIFFE. Usar uma string SPIFFE para uma vinculação de política do IAM retorna um erro INVALID_ARGUMENT.
  • Agentes executados fora do Google Cloud: agentes externos ou locais precisam federar a identidade externa usando a Federação de identidade da carga de trabalho ou usar uma conta de serviço padrão para interagir com os recursos do Google Cloud . Depois de autenticada, essa string de identidade da carga de trabalho federada ou o e-mail da conta de serviço atua como o principal do agente nas políticas do IAM.

Para agentes executados em Google Cloud, como o principal do agente gerenciado está vinculado diretamente ao recurso de computação do ambiente de execução do agente, a string principal incorpora o caminho completo para esse recurso de computação subjacente.

O IAM oferece suporte à governança do acesso do agente nos seguintes escopos:

  • Instância de um único mecanismo: concede permissões a uma implantação específica do agente. Por exemplo, uma instância individual do Agent Runtime é representada por uma única string principal: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID
  • Escopo do projeto: concede permissões a todos os mecanismos de raciocínio em execução em um projeto específico por um conjunto principal: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
  • Escopo em toda a organização: concede permissões a todos os agentes da organização usando um curinga de conjunto principal: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*

O Agent Registry mostra o principal do agente individual como um atributo somente de saída quando você consulta os detalhes de um agente.

Referências de ambiente de execução

Uma referência de tempo de execução aponta para a infraestrutura de computação em que o código de um agente, servidor MCP ou endpoint é executado. Por exemplo, uma referência de tempo de execução pode apontar para um mecanismo de raciocínio do Agent Runtime, uma implantação do GKE ou um serviço do Cloud Run.

A string principal de um agente inclui o caminho de referência do ambiente de execução, que vincula as permissões do IAM diretamente ao local de execução do agente. Se você registrar um agente em um projeto diferente de onde ele foi implantado, a referência de tempo de execução apontará para o projeto que hospeda a carga de trabalho subjacente.

Na API Agent Registry, a referência de tempo de execução é representada pelo atributo agentregistry.googleapis.com/system/RuntimeReference, que contém o caminho de computação ou infraestrutura no campo uri. É possível conferir esse atributo somente de saída como parte dos detalhes do agente ou usá-lo para consultar fluxos de tráfego e relações no gráfico de topologia.

A seguir