Identität und Kennungen

Um Agenten zu registrieren und in der Agent Registry zu verwalten, arbeiten Sie mit vier Architekturschichten. Für jede Ebene wird ein bestimmter Namens-, Identitäts- oder Routingmechanismus verwendet:

  • Registry-Kennungen (Agent-Kennungen, MCP-Server-Kennungen und Endpunkt-Kennungen): Logische, unveränderliche Uniform Resource Names (URNs), die für die Bestandsverfolgung, die Registry-Erkennung und die Filterung verwendet werden. Diese URNs werden nicht für die Laufzeit-Governance verwendet.
  • Ressourcennamen: Standardmäßig global eindeutigeGoogle Cloud Ressourcennamen (registryResource oder name), die bei der Registrierung generiert und von Agent Gateway-Routenregeln, IAP-Ausgangsrichtlinien (Identity-Aware Proxy) und IAM-Richtlinienbindungen (Identity and Access Management) verwendet werden.
  • Agenten-Prinzipale: Überprüfbare IAM-Identitäten wie SPIFFE-IDs für Agents, die aufGoogle Cloud ausgeführt werden, oder Dienstkonten für externe Agents, die für die Authentifizierung, Autorisierung und das Audit-Logging von Aufrufern verwendet werden.
  • Laufzeitreferenzen: Compute- oder Infrastrukturpfade (RuntimeReference), die für Topologieabfragen und den Abgleich von ausgehendem Traffic verwendet werden.

In der folgenden Tabelle werden die einzelnen Ebenen, ihr primärer Zweck, die nachgelagerte Governance-Rolle und die Syntax verglichen:

Ebene Hauptzweck Governance-Rolle Syntax
Registry-Kennungen
(Kennungen für Agenten, MCP-Server oder Endpunkte)		 Stabile Registrierungserkennung, Metadaten-Tagging und Suche. Unveränderlich und nicht für die Governance verwendet.
  • urn:agent:IDENTIFIER
  • urn:mcp:IDENTIFIER
  • urn:endpoint:IDENTIFIER
Ressourcenname Identifizierung der Zielressource für die Richtliniendurchsetzung. Gemäß den Richtlinien erforderlich und wird von Agent Gateway-Routen und IAP-Bindungen verwendet.
  • 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 Anruferauthentifizierung, Autorisierung und Audit-Logging. Von IAM erzwungen.
  • principal://PRINCIPAL_PATH
  • principalSet://PRINCIPAL_SET_PATH
Laufzeitreferenz Physisches Compute-Routing und Abgleich des ausgehenden Traffics. Wird in Topologieanfragen und im Agent Gateway ausgewertet, um Netzwerkverkehr abzugleichen. agentregistry.googleapis.com/system/RuntimeReference mit dem Compute- oder Infrastrukturpfad als uri: "RUNTIME_URI"

Registrierungs-IDs

Eine Registry-Kennung ist ein global eindeutiger, unveränderlicher Uniform Resource Name (URN), der einer registrierten Komponente von der Agent Registry zugewiesen wird. Dieser URN bietet eine stabile Referenz für Nutzer und Orchestrator-Agents, um Komponenten in der Agent Registry zu finden, zu filtern und zu suchen. Er bleibt konstant, unabhängig von zugrunde liegenden Infrastrukturmigrationen oder Code-Updates.

Registrierungs-IDs sind logische URNs, die ausschließlich für die Registrierungssuche und die Metadatenannotation verwendet werden. Sie unterscheiden sich von Laufzeitsicherheitsidentitäten und Ressourcennamen und können nicht in IAM-Richtlinienbindungen, Autorisierungsheadern oder Agent Gateway-Routenregeln verwendet werden.

In der Agent Registry werden drei Arten von Registry-IDs verwendet:

KI-Agenten-IDs

In der Agent Registry wird allen registrierten Agenten eine Agent-ID (agentId) zugewiesen, einschließlich von Google verwalteter Agenten und externer oder benutzerdefinierter Agenten. Wenn Sie die sichere, richtlinienkonforme Kommunikation für einen Agenten verwalten möchten, verwenden Sie seinen Agenten-Prinzipal anstelle seiner Agenten-ID.

In der Agent Registry werden Agent-IDs während der Aufnahme automatisch generiert. Die genaue URN-Struktur hängt von der Rechenumgebung ab, in der der Agent bereitgestellt wird:

  • Agent Runtime in der Gemini Enterprise Agent Platform: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID
  • Cloud Run-Dienste: 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
  • GKE-Deployments: 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
  • Manuell registrierte Agents: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:AGENT_ID

MCP-Server-IDs

Eine MCP-Server-ID (mcpServerId) ist eine Registry-ID, mit der ein MCP-Server und seine Tools in Agent Registry ermittelt werden können.

MCP-Server reagieren nur auf Anfragen und haben keinen IAM-Principal. Wenn ein Agent Tools auf einem MCP-Server aufruft, wird der Zugriff mit dem aufrufenden Agenten-Prinzipal autorisiert.

Das URN-Format hängt davon ab, ob der Server ein von Google verwalteter Dienst oder ein extern registrierter Server ist:

  • Google- und Google Cloud Remote-MCP-Server: urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID
  • Manuell registrierte MCP-Server: urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID

Endpunkt-IDs

Eine Endpunkt-ID (endpointId) ist eine Registrierungs-ID, die einem registrierten Endpunkt zugewiesen wird, um Ziel-API-Ziele zu ermitteln.

Das URN-Format für manuell registrierte Endpunkte ist urn:endpoint:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:ENDPOINT_ID.

Ressourcennamen

Wenn Sie einen KI-Agenten, einen MCP-Server oder einen Endpunkt in der Agent Registry registrieren, wird im Registrierungsprozess ein standardmäßiger Google Cloud Ressourcennamen im Format eines hierarchischen URI-Pfads generiert:

  • KI-Agents: projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID
  • MCP-Server: projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID
  • Endpunkte: projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID

Wenn Sie eine beschreibbare Service-Ressource erstellen oder untersuchen, z. B. durch Ausführen von gcloud agent-registry services describe, wird dieser Ressourcenname im Nur-Ausgabe-Feld registryResource zurückgegeben. Wenn Sie die resultierende Ressource Agent, McpServer oder Endpoint mit Lesezugriff direkt abfragen oder untersuchen, z. B. mit dem Befehl gcloud agent-registry agents describe, wird dieser Ressourcenname im Standardfeld name zurückgegeben.

Ressourcennamen können verwendet werden, um Richtlinien zu binden, Netzwerkverkehr weiterzuleiten und Zugriffssteuerungen zu konfigurieren. Nachgelagerte Governance-Oberflächen, einschließlich Agent Gateway-Routenregeln, IAP-Ausgangsrichtlinien und IAM-Ressourcenrichtlinien, werden anhand dieses Ressourcennamens ausgewertet. Sie akzeptieren keine URNs von Registry-Kennungen wie Agent-Kennungen, MCP-Server-Kennungen oder Endpunkt-Kennungen.

Wenn Sie in einer Richtlinienbindung oder Routenregel anstelle des Ressourcennamens einen Registrierungs-ID-URN verwenden, gibt die API einen NOT_FOUND: Requested entity was not found.-Fehler zurück. Wenn dieser Fehler bei der Konfiguration von Governance-Richtlinien auftritt, prüfen Sie Folgendes:

  • Registrierungsstatus: Prüfen Sie, ob der Ziel-KI-Agent, der MCP-Server oder der Endpunkt in Agent Registry am erwarteten Speicherort registriert ist.
  • Format des Bezeichners: Prüfen Sie, ob in Ihrer Richtlinienbindung oder Routenregel der Standardressourcenname (projects/PROJECT_NUMBER/locations/LOCATION/.../agentregistry-ID) anstelle des URN des Registrierungsbezeichners angegeben ist.

Agenten-Principals

Ein Agent-Prinzipal ist die Sicherheitsidentität eines Agenten in IAM. Wie ein Nutzer oder ein Dienstkonto verwendet ein Agent sein Hauptkonto, um Berechtigungen zu erhalten und Downstream-Dienste aufzurufen. Wenn Sie IAM-Richtlinien konfigurieren, verwenden Sie den Hauptkontostring des Agents, um Zugriff zu gewähren oder einzuschränken.

In Agent Registry hängt es davon ab, wo ein Agent ausgeführt wird, wie er als Prinzipal identifiziert wird:

  • Agents,die auf der Google Cloud Infrastruktur ausgeführt werden: Für verwaltete Laufzeiten wie die Agent Runtime on Gemini Enterprise Agent Platform Google Cloudwird automatisch eine verwaltete Workload Identity im Format einer SPIFFE-ID bereitgestellt, die direkt an die Computerlaufzeit des Agenten gebunden ist. Wenn Sie in IAM-Zulassungsrichtlinien und ‑Bindungen auf diese Identität verweisen, müssen Sie das IAM-Hauptkonto oder das Hauptkonto-Set-Stringformat anstelle des SPIFFE-URI-Schemas verwenden. Wenn Sie einen SPIFFE-String für eine IAM-Richtlinienbindung verwenden, wird ein INVALID_ARGUMENT-Fehler zurückgegeben.
  • Agents, die außerhalb von Google Cloudausgeführt werden: Externe oder lokale Agents müssen ihre externe Identität über die Workload Identity-Föderation föderieren oder ein Standarddienstkonto verwenden, um mit Google Cloud -Ressourcen zu interagieren. Nach der Authentifizierung fungiert dieser String für die föderierte Workload Identity oder die E-Mail-Adresse des Dienstkontos als Agenten-Prinzipal in IAM-Richtlinien.

Bei Agenten, die auf Google Cloudausgeführt werden, ist der verwaltete Agenten-Prinzipal direkt an die Rechenressource der Laufzeit des Agenten gebunden. Daher enthält der Prinzipalstring den vollständigen Pfad zu dieser zugrunde liegenden Rechenressource.

IAM unterstützt die Steuerung des Agent-Zugriffs in den folgenden Bereichen:

  • Einzelne Engine-Instanz: Gewährt Berechtigungen für eine bestimmte Agent-Bereitstellung. Eine einzelne Agent Runtime-Instanz wird beispielsweise durch einen einzelnen Prinzipalstring dargestellt: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID
  • Projektbereich: Gewährt Berechtigungen für alle Reasoning Engines, die in einem bestimmten Projekt über einen Hauptkontosatz ausgeführt werden: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
  • Organisationsweiter Bereich: Gewährt Berechtigungen für alle Agents in der gesamten Organisation über einen Platzhalter für die Hauptgruppe:principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*

In der Agent Registry wird der einzelne Agenten-Prinzipal als reines Ausgabeargument angezeigt, wenn Sie die Details eines Agenten aufrufen.

Laufzeitreferenzen

Eine Laufzeitreferenz verweist auf die zugrunde liegende Recheninfrastruktur, auf der der Code für einen KI-Agenten, einen MCP-Server oder einen Endpunkt ausgeführt wird. Eine Laufzeitreferenz kann beispielsweise auf eine Agent Runtime Reasoning Engine, eine GKE-Bereitstellung oder einen Cloud Run-Dienst verweisen.

Der Hauptkontostring eines Agents enthält seinen Laufzeitreferenzpfad, wodurch IAM-Berechtigungen direkt an den Ort gebunden werden, an dem der Agent ausgeführt wird. Wenn Sie einen Agent in einem anderen Projekt als dem registrieren, in dem er bereitgestellt wird, verweist die Laufzeit auf das Projekt, in dem die zugrunde liegende Arbeitslast gehostet wird.

In der Agent Registry API wird die Laufzeitreferenz durch das Attribut agentregistry.googleapis.com/system/RuntimeReference dargestellt, das den Compute- oder Infrastrukturpfad im Feld uri enthält. Sie können dieses Attribut, das nur ausgegeben wird, in den Agentendetails ansehen oder damit Traffic-Flüsse und Beziehungen im Topologie-Diagramm abfragen.

Nächste Schritte