Identité et identifiants

Pour enregistrer et gérer les agents dans Agent Registry, vous travaillez sur quatre couches architecturales. Chaque couche utilise un mécanisme de dénomination, d'identité ou de routage spécifique :

  • Identifiants du registre (identifiants d'agent, identifiants de serveur MCP et identifiants de point de terminaison) : noms de ressources uniformes (URN) logiques et immuables utilisés pour le suivi de l'inventaire, la découverte du registre et le filtrage. Ces URN ne sont pas utilisées pour la gouvernance de l'exécution.
  • Noms de ressources : noms de ressourcesGoogle Clouduniques au niveau mondial (registryResource ou name) générés lors de l'enregistrement et utilisés par les règles de routage Agent Gateway, les règles de sortie Identity-Aware Proxy (IAP) et les liaisons de stratégie Identity and Access Management (IAM).
  • Comptes principaux de l'agent : identités IAM vérifiables, telles que les ID SPIFFE pour les agents s'exécutant surGoogle Cloud ou les comptes de service pour les agents externes, utilisées pour l'authentification, l'autorisation et la journalisation d'audit de l'appelant.
  • Références d'exécution : chemins de calcul ou d'infrastructure (RuntimeReference) utilisés pour les requêtes de topologie et la mise en correspondance du trafic sortant.

Le tableau suivant compare chaque couche, son objectif principal, son rôle de gouvernance en aval et sa syntaxe :

intégrée Objectif principal Rôle de gouvernance Syntaxe
Identifiants du registre
(identifiants d'agent, de serveur MCP ou de point de terminaison)		 Découverte, ajout de tags aux métadonnées et recherche de registres stables. Immuable et non utilisé pour la gouvernance.
  • urn:agent:IDENTIFIER
  • urn:mcp:IDENTIFIER
  • urn:endpoint:IDENTIFIER
Nom de la ressource Identification de la ressource cible pour l'application des règles. Requis par les règles et utilisé par les routes Agent Gateway et les liaisons 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 Authentification de l'appelant, autorisation et journaux d'audit. Appliqué par IAM.
  • principal://PRINCIPAL_PATH
  • principalSet://PRINCIPAL_SET_PATH
Référence d'exécution Routage du calcul physique et correspondance du trafic sortant. Évalué dans les requêtes de topologie et dans Agent Gateway pour correspondre au trafic réseau. agentregistry.googleapis.com/system/RuntimeReference contenant le chemin de calcul ou d'infrastructure sous la forme uri: "RUNTIME_URI"

Identifiants de registre

Un identifiant de registre est un nom de ressource uniforme (URN) immuable et unique au niveau mondial que le registre d'agents attribue à un composant enregistré. Cet URN fournit une référence stable permettant aux consommateurs et aux agents d'orchestration de découvrir, de filtrer et de rechercher des composants dans le registre d'agents. Il reste constant, quelles que soient les migrations d'infrastructure ou les mises à jour de code sous-jacentes.

Les identifiants de registre sont des URN logiques utilisées exclusivement pour la découverte de registre et l'annotation de métadonnées. Elles diffèrent des identités de sécurité et des noms de ressources d'exécution, et ne peuvent pas être utilisées dans les liaisons de stratégie IAM, les en-têtes d'autorisation ni les règles de routage de l'Agent Gateway.

Le registre d'agents utilise trois types d'identifiants de registre :

Identifiants d'agent

Agent Registry attribue un identifiant d'agent (agentId) à tous les agents enregistrés, y compris les agents gérés par Google et les agents externes ou personnalisés. Pour gérer la communication sécurisée et régie par des règles pour un agent, utilisez son compte principal d'agent plutôt que son identifiant d'agent.

Le registre d'agents génère automatiquement des identifiants d'agent lors de l'ingestion. La structure exacte de l'URN dépend de l'environnement de calcul dans lequel l'agent est déployé :

  • Environnement d'exécution de l'agent sur Gemini Enterprise Agent Platform : urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID
  • Services Cloud Run : urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME
  • Jobs Cloud Run : urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME
  • Déploiements 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
  • Agents enregistrés manuellement : urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:AGENT_ID

Identifiants de serveur MCP

Un identifiant de serveur MCP (mcpServerId) est un identifiant de registre utilisé pour découvrir un serveur MCP et ses outils dans Agent Registry.

Les serveurs MCP ne répondent qu'aux requêtes et ne disposent pas d'un principal IAM. Lorsqu'un agent appelle des outils sur un serveur MCP, l'accès est autorisé à l'aide du principal de l'agent appelant.

Le format de l'URN dépend du fait que le serveur soit un service géré par Google ou un serveur externe enregistré :

  • Serveurs MCP Google et Google Cloud distants : urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID
  • Serveurs MCP enregistrés manuellement : urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID

Identifiants de point de terminaison

Un identifiant de point de terminaison (endpointId) est un identifiant de registre attribué à un point de terminaison enregistré pour la découverte des destinations d'API cibles.

Le format URN pour les points de terminaison enregistrés manuellement est urn:endpoint:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:ENDPOINT_ID.

Noms de ressources

Lorsque vous enregistrez un agent, un serveur MCP ou un point de terminaison dans Agent Registry, le processus d'enregistrement génère un Google Cloudstandard nom de ressource au format d'un chemin d'URI hiérarchique :

  • Agents : projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID
  • Serveurs MCP : projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID
  • Points de terminaison : projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID

Lorsque vous créez ou inspectez une ressource Service accessible en écriture, par exemple en exécutant gcloud agent-registry services describe, ce nom de ressource est renvoyé dans le champ registryResource en sortie uniquement. Lorsque vous interrogez ou inspectez directement la ressource Agent, McpServer ou Endpoint en lecture seule résultante, par exemple à l'aide de la commande gcloud agent-registry agents describe, ce nom de ressource est renvoyé dans le champ name standard.

Les noms de ressources peuvent être utilisés pour associer des règles, acheminer le trafic réseau et configurer des contrôles d'accès. Les surfaces de gouvernance en aval, y compris les règles de routage Agent Gateway, les règles de sortie IAP et les règles de ressources IAM, sont évaluées par rapport à ce nom de ressource. Ils n'acceptent pas les URN provenant des identifiants de registre, tels que les identifiants d'agent, les identifiants de serveur MCP ou les identifiants de point de terminaison.

Si vous utilisez un URN d'identifiant de registre dans une liaison de stratégie ou une règle de route au lieu du nom de ressource, l'API renvoie une erreur NOT_FOUND: Requested entity was not found.. Si vous rencontrez cette erreur lors de la configuration des règles de gouvernance, vérifiez les points suivants :

  • État de l'enregistrement : vérifiez que l'agent, le serveur MCP ou le point de terminaison cible sont enregistrés dans Agent Registry à l'emplacement prévu.
  • Format de l'identifiant : vérifiez que votre association de règles ou règle de route spécifie le nom de ressource standard (projects/PROJECT_NUMBER/locations/LOCATION/.../agentregistry-ID) plutôt que l'URN de l'identifiant de registre.

Entités principales de l'agent

Un compte principal d'agent est l'identité de sécurité d'un agent dans IAM. Comme un compte utilisateur ou de service, un agent utilise son compte principal pour détenir des autorisations et appeler des services en aval. Lorsque vous configurez des règles IAM, vous utilisez la chaîne de compte principal de l'agent pour accorder ou restreindre l'accès.

Dans Agent Registry, la façon dont un agent est identifié comme principal dépend de l'endroit où il s'exécute :

  • Agents s'exécutant sur l'infrastructure Google Cloud  : pour les runtimes gérés tels qu'Agent Runtime sur Gemini Enterprise Agent Platform, Google Cloudprovisionne automatiquement une Workload Identity gérée au format ID SPIFFE, qui est directement liée au runtime de calcul de l'agent. Lorsque vous référencez cette identité dans les liaisons et les règles d'autorisation IAM, vous devez utiliser le format de chaîne de compte principal ou d'ensemble de comptes principaux IAM plutôt que le schéma d'URI SPIFFE. L'utilisation d'une chaîne SPIFFE pour une liaison de stratégie IAM renvoie une erreur INVALID_ARGUMENT.
  • Agents exécutés en dehors de Google Cloud : les agents externes ou sur site doivent fédérer leur identité externe via la fédération d'identité de charge de travail ou utiliser un compte de service standard pour interagir avec les ressources Google Cloud . Une fois authentifiée, cette chaîne d'identité Workload Identity fédérée ou cet e-mail de compte de service sert de compte principal d'agent dans les stratégies IAM.

Pour les agents s'exécutant sur Google Cloud, étant donné que le principal de l'agent géré est directement lié à la ressource de calcul de l'environnement d'exécution de l'agent, la chaîne principale intègre le chemin d'accès complet à cette ressource de calcul sous-jacente.

IAM permet de régir l'accès des agents dans les champs d'application suivants :

  • Instance de moteur unique : accorde des autorisations à un déploiement d'agent spécifique. Par exemple, une instance Agent Runtime individuelle est représentée par une seule chaîne principale : principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID.
  • Champ d'application du projet : accorde des autorisations à tous les moteurs de raisonnement s'exécutant dans un projet spécifique via un ensemble de comptes principaux : principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
  • Champ d'application à l'échelle de l'organisation : accorde des autorisations à tous les agents de l'ensemble de l'organisation via un caractère générique de l'ensemble de comptes principaux : principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*

Agent Registry affiche le compte principal de l'agent individuel en tant qu'attribut en sortie uniquement lorsque vous affichez les détails d'un agent.

Références d'exécution

Une référence d'exécution pointe vers l'infrastructure de calcul sous-jacente sur laquelle s'exécute le code d'un agent, d'un serveur MCP ou d'un point de terminaison. Par exemple, une référence de temps d'exécution peut pointer vers un moteur de raisonnement Agent Runtime, un déploiement GKE ou un service Cloud Run.

La chaîne principale d'un agent inclut son chemin d'accès de référence à l'exécution, qui associe les autorisations IAM directement à l'emplacement où l'agent s'exécute. Si vous enregistrez un agent dans un projet différent de celui dans lequel il est déployé, la référence d'exécution pointe vers le projet hébergeant la charge de travail sous-jacente.

Dans l'API Agent Registry, la référence d'exécution est représentée par l'attribut agentregistry.googleapis.com/system/RuntimeReference, qui contient le chemin de calcul ou d'infrastructure dans son champ uri. Vous pouvez afficher cet attribut en sortie uniquement dans les détails de l'agent ou l'utiliser pour interroger les flux de trafic et les relations dans le graphique de topologie.

Étapes suivantes