Identità e identificatori

Per registrare e gestire gli agenti in Agent Registry, devi lavorare su quattro livelli architetturali. Ogni livello utilizza un meccanismo specifico di denominazione, identità o routing:

  • Identificatori del registry (identificatori dell'agente, identificatori del server MCP e identificatori dell'endpoint): nomi di risorse uniformi (URN) logici e immutabili utilizzati per il monitoraggio dell'inventario, l'individuazione del registry e il filtraggio. Questi URN non vengono utilizzati per la governance in fase di runtime.
  • Nomi delle risorse: nomi delle risorse Google Cloud univoci a livello globale (registryResource o name) generati al momento della registrazione e utilizzati dalle regole di routing di Agent Gateway, dalle policy di uscita di Identity-Aware Proxy (IAP) e dalle associazioni di policy IAM (Identity and Access Management).
  • Entità dell'agente: identità IAM verificabili, come ID SPIFFE per gli agenti in esecuzione suGoogle Cloud o service account per agenti esterni, utilizzati per l'autenticazione, l'autorizzazione e gli audit log del chiamante.
  • Riferimenti di runtime: percorsi di calcolo o infrastruttura (RuntimeReference) utilizzati per le query di topologia e la corrispondenza del traffico in uscita.

La tabella seguente confronta ogni livello, il suo scopo principale, il ruolo di governance downstream e la sintassi:

incorporato Scopo principale Ruolo di governance Sintassi
Identificatori del registro
(identificatori di agenti, server MCP o endpoint)		 Individuazione, tagging dei metadati e ricerca del registro stabili. Immutabile e non utilizzato per la governance.
  • urn:agent:IDENTIFIER
  • urn:mcp:IDENTIFIER
  • urn:endpoint:IDENTIFIER
Nome della risorsa Identificazione della risorsa di destinazione per l'applicazione delle policy. Richiesto dalle policy e utilizzato dalle route di Agent Gateway e dai binding 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
Agent principal Autenticazione, autorizzazione e logging di controllo del chiamante. Applicata in modo forzato da IAM.
  • principal://PRINCIPAL_PATH
  • principalSet://PRINCIPAL_SET_PATH
Riferimento al runtime Routing di calcolo fisico e corrispondenza del traffico in uscita. Valutato nelle query di topologia e in Agent Gateway per la corrispondenza del traffico di rete. agentregistry.googleapis.com/system/RuntimeReference contenente il percorso di calcolo o dell'infrastruttura come uri: "RUNTIME_URI"

Identificatori del registro

Un identificatore del registro è un nome della risorsa uniforme (URN) univoco e immutabile a livello globale che Agent Registry assegna a un componente registrato. Questo URN fornisce un riferimento stabile per i consumer e gli agenti orchestratori per scoprire, filtrare e cercare i componenti nel registro degli agenti, rimanendo costante indipendentemente dalle migrazioni dell'infrastruttura sottostante o dagli aggiornamenti del codice.

Gli identificatori del registro sono URN logici utilizzati esclusivamente per l'individuazione del registro e l'annotazione dei metadati. Sono diversi dalle identità di sicurezza di runtime e dai nomi delle risorse e non possono essere utilizzati nei binding delle policy IAM, nelle intestazioni di autorizzazione o nelle regole di instradamento dell'Agent Gateway.

Il registro degli agenti utilizza tre tipi di identificatori del registro:

Identificatori dell'agente

Agent Registry assegna un identificatore dell'agente (agentId) a tutti gli agenti registrati, inclusi gli agenti gestiti da Google e gli agenti esterni o personalizzati. Per gestire la comunicazione sicura e regolata dalle policy per un agente, utilizza la relativa entità dell'agente anziché il relativo identificatore.

Il registro degli agenti genera automaticamente gli identificatori degli agenti durante l'importazione. La struttura esatta dell'URN dipende dall'ambiente di calcolo in cui viene eseguito il deployment dell'agente:

  • Agent Runtime su Gemini Enterprise Agent Platform: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID
  • Servizi Cloud Run: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME
  • Cloud Run Jobs: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME
  • Deployment 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
  • Agenti registrati manualmente: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:AGENT_ID

Identificatori del server MCP

Un identificatore del server MCP (mcpServerId) è un identificatore del registro utilizzato per individuare un server MCP e i relativi strumenti in Agent Registry.

I server MCP rispondono solo alle richieste e non hanno un principal IAM. Quando un agente richiama gli strumenti su un server MCP, l'accesso viene autorizzato utilizzando l'entità dell'agente chiamante.

Il formato URN dipende dal fatto che il server sia un servizio gestito da Google o un server esterno registrato:

  • Google e Google Cloud server MCP remoti: urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID
  • Server MCP registrati manualmente: urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID

Identificatori endpoint

Un identificatore endpoint (endpointId) è un identificatore del registro assegnato a un endpoint registrato per scoprire le destinazioni API di destinazione.

Il formato URN per gli endpoint registrati manualmente è urn:endpoint:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:ENDPOINT_ID.

Nomi delle risorse

Quando registri un agente, un server MCP o un endpoint in Agent Registry, la procedura di registrazione genera un Google Cloud nome risorsa standard formattato come percorso URI gerarchico:

  • Agenti: projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID
  • Server MCP: projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID
  • Endpoint: projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID

Quando crei o esamini una risorsa Service scrivibile, ad esempio eseguendo gcloud agent-registry services describe, questo nome di risorsa viene restituito nel campo registryResource di sola output. Quando esegui una query o ispezioni la risorsa Agent, McpServer o Endpoint di sola lettura risultante direttamente, ad esempio utilizzando il comando gcloud agent-registry agents describe, questo nome della risorsa viene restituito nel campo standard name.

I nomi delle risorse possono essere utilizzati per associare policy, instradare il traffico di rete e configurare i controlli dell'accesso. Le superfici di governance downstream, incluse le regole di instradamento di Agent Gateway, le policy in uscita IAP e le policy delle risorse IAM, vengono valutate in base a questo nome risorsa. Non accettano URN da identificatori del registry, ad esempio identificatori dell'agente, identificatori del server MCP o identificatori dell'endpoint.

Se utilizzi un URN identificatore del registro in un binding di policy o in una regola di instradamento anziché il nome della risorsa, l'API restituisce un errore NOT_FOUND: Requested entity was not found.. Se si verifica questo errore durante la configurazione delle norme di governance, verifica quanto segue:

  • Stato della registrazione: verifica che l'agente di destinazione, il server MCP o l'endpoint sia registrato in Agent Registry nella posizione prevista.
  • Formato identificatore: verifica che l'associazione delle policy o la regola di instradamento specifichi il nome della risorsa standard (projects/PROJECT_NUMBER/locations/LOCATION/.../agentregistry-ID) anziché l'URN dell'identificatore del registry.

Entità dell'agente

Un'entità dell'agente è l'identità di sicurezza di un agente in IAM. Proprio come un utente o un account di servizio, un agente utilizza la propria entità per detenere le autorizzazioni e chiamare i servizi downstream. Quando configuri i criteri IAM, utilizzi la stringa principale dell'agente per concedere o limitare l'accesso.

In Agent Registry, il modo in cui un agente viene identificato come entità dipende da dove viene eseguito:

  • Agenti in esecuzione su Google Cloud infrastruttura: per runtime gestiti come Agent Runtime su Gemini Enterprise Agent Platform, Google Cloudviene eseguito automaticamente il provisioning di una Workload Identity gestita formattata come ID SPIFFE, che è associata direttamente al runtime di calcolo dell'agente. Quando fai riferimento a questa identità nelle policy e nei binding di autorizzazione IAM, devi utilizzare il formato stringa dell'entità IAM o del set di entità anziché lo schema URI SPIFFE. L'utilizzo di una stringa SPIFFE per un binding di policy IAM restituisce un errore INVALID_ARGUMENT.
  • Agenti in esecuzione all'esterno di Google Cloud: gli agenti esterni o on-premise devono federare la propria identità esterna tramite la federazione delle identità per i workload o utilizzare un account di servizio standard per interagire con le risorse Google Cloud . Una volta autenticata, questa stringa di Workload Identity federata o l'email del account di servizio funge da entità dell'agente nelle policy IAM.

Per gli agenti in esecuzione su Google Cloud, poiché il principal dell'agente gestito è associato direttamente alla risorsa di computing del runtime dell'agente, la stringa del principal incorpora il percorso completo della risorsa di computing sottostante.

IAM supporta la gestione dell'accesso degli agenti nei seguenti ambiti:

  • Singola istanza del motore: concede le autorizzazioni a un deployment dell'agente specifico. Ad esempio, una singola istanza di Agent Runtime è rappresentata da una singola stringa principale: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID
  • Ambito del progetto: concede autorizzazioni a tutti i motori di ragionamento in esecuzione all'interno di un progetto specifico tramite un set di entità: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
  • Ambito a livello di organizzazione: concede le autorizzazioni a tutti gli agenti dell'intera organizzazione tramite un carattere jolly del set di entità:principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*

Agent Registry mostra l'entità dell'agente individuale come attributo di sola uscita quando visualizzi i dettagli di un agente.

Riferimenti di runtime

Un riferimento al runtime punta all'infrastruttura di calcolo sottostante in cui viene eseguito il codice per un agente, un server MCP o un endpoint. Ad esempio, un riferimento al runtime può puntare a un motore di ragionamento Agent Runtime, a un deployment GKE o a un servizio Cloud Run.

La stringa principale di un agente include il percorso di riferimento del runtime, che collega le autorizzazioni IAM direttamente al punto in cui viene eseguito l'agente. Se registri un agente in un progetto diverso da quello in cui è implementato, il riferimento di runtime punta al progetto che ospita il carico di lavoro sottostante.

Nell'API Agent Registry, il riferimento al runtime è rappresentato dall'attributo agentregistry.googleapis.com/system/RuntimeReference, che contiene il percorso di calcolo o dell'infrastruttura nel campo uri. Puoi visualizzare questo attributo di sola output come parte dei dettagli dell'agente o utilizzarlo per eseguire query sui flussi di traffico e sulle relazioni nel grafico della topologia.

Passaggi successivi