Das Agent2Agent-Protokoll (A2A) ist ein offenes Kommunikationsprotokoll und eine universelle Sprache für Agenten. So können Agenten von verschiedenen Entwicklern und Plattformen einander finden, zusammenarbeiten und Aufgaben sicher delegieren. In diesem Dokument wird beschrieben, wie Gemini Enterprise-Administratoren Agenten, die mit A2A erstellt wurden und auf einer beliebigen Plattform gehostet werden, mit Gemini Enterprise verbinden und so für Nutzer in der Gemini Enterprise Web-App verfügbar machen können.
Hinweis
Sie benötigen Folgendes:
Die Rolle Gemini Enterprise Admin.
Aktivieren Sie die Discovery Engine API. Wenn Sie die Discovery Engine API für das Google Cloud-Projekt aktivieren möchten, rufen Sie in der Google Cloud Console die Seite Discovery Engine API auf.
Eine vorhandene Gemini Enterprise-App. Informationen zum Erstellen einer App finden Sie unter App erstellen.
Ein Agent, der das A2A-Protokoll verwendet.
Gemini Enterprise unterstützt den A2A v0.3-Streaming-Mechanismus.
Wenn Sie A2A v1.0.0 oder höher verwenden, nutzen Sie die vom SDK bereitgestellten Kompatibilitätspakete, um sicherzustellen, dass Ihr Agent mit dem früheren Mechanismus funktioniert (z. B. das Paket
a2acompat/a2av0für Go oder das Paketa2a.compat.v0_3für Python).Wenn Ihr A2A-Agent in Cloud Run gehostet wird, direkt eine Standard-
.run.app-URL verwendet und eine Authentifizierung erfordert, weisen Sie dem Discovery Engine-Dienst-Agent die Rolle „Cloud Run-Aufrufer“ (roles/run.invoker) zu. Dies gilt nicht, wenn Cloud Run hinter Apigee, einem Load Balancer oder einer benutzerdefinierten Domain liegt:gcloud projects add-iam-policy-binding <var>PROJECT_ID</var> \ --member="serviceAccount:service-<var>PROJECT_NUMBER</var>@gcp-sa-discoveryengine.iam.gserviceaccount.com" \ --role="roles/run.invoker"Ersetzen Sie Folgendes:
PROJECT_ID: die Projekt-ID.PROJECT_NUMBER: Die Nummer Ihres Projekts in Google Cloud .
Authentifizierung und Autorisierung konfigurieren
Je nach Hosting-Umgebung und Sicherheitsanforderungen Ihres KI-Agenten können Sie konfigurieren, wie sich Gemini Enterprise bei Ihrem KI-Agenten authentifiziert, wie Ihr KI-Agent im Namen des Endnutzers auf nachgelagerte Ressourcen und Tools zugreift und wie Sie den Endpunkt Ihres KI-Agenten sichern:
- So authentifiziert sich Gemini Enterprise bei Ihrem Agenten: Hier erfahren Sie, wie Gemini Enterprise beim Aufrufen Ihres A2A-Agent-Endpunkts IAM-Header für die Dienst-zu-Dienst-Kommunikation und OAuth 2.0-Header für Endnutzer sendet.
- OAuth 2.0 für die Endnutzerautorisierung konfigurieren:
Konfigurieren Sie eine OAuth 2.0-Autorisierungsressource in Gemini Enterprise, damit Gemini Enterprise ein Endnutzertoken abruft und es im
Authorization-Header sendet, wenn Ihr Agent aufgerufen wird (z. B. um einen A2A-Agenten aufzurufen, der in Agent Runtime auf der Gemini Enterprise Agent Platform gehostet wird, oder um ein Nutzertoken direkt an Ihren Agentencontainer zu übergeben). - Dreibeiniges OAuth mit dem Agent Identity-Authentifizierungsmanager konfigurieren: Konfigurieren Sie einen dreibeinigen OAuth-Authentifizierungsanbieter (3LO) im Agent Identity-Authentifizierungsmanager, damit Ihr A2A-Agent bei Bedarf vom Nutzer delegierte Tokens für bestimmte Tools wie MCP-Server (Model Context Protocol) oder APIs von Drittanbietern anfordern kann.
So authentifiziert sich Gemini Enterprise bei Ihrem KI-Agenten
Wenn Gemini Enterprise einen A2A-Agenten aufruft, kann es je nach Hosting- und Sicherheitskonfiguration Authentifizierungs- und Autorisierungsdaten in Anfrageheadern senden:
| Header | Beschreibung |
|---|---|
X-Serverless-Authorization |
IAM-Authentifizierung von Dienst zu Dienst (für Cloud Run). Wenn Ihr A2A-Agent in Cloud Run gehostet wird und die Agenten-URL eine Standard- Wenn Gemini Enterprise eine Standard- |
Authorization |
OAuth 2.0-Autorisierung für Endnutzer (für Endpunktaufruf, Nutzerkontext und API-Zugriff). Wenn Sie OAuth 2.0-Anmeldedaten für Ihren A2A-Agenten konfigurieren (siehe OAuth 2.0 für die Endnutzerautorisierung konfigurieren), ruft Gemini Enterprise im Namen des angemeldeten Endnutzers ein OAuth 2.0-Zugriffstoken oder -ID-Token ab, nachdem dieser seine Einwilligung erteilt hat, und sendet es im Standard- Bei in Cloud Run gehosteten Agenten leitet Cloud Run den Header |
OAuth 2.0 für die Endnutzerautorisierung konfigurieren (optional)
Konfigurieren Sie für A2A-Agenten OAuth 2.0-Anmeldedaten in Gemini Enterprise, wenn Ihr Agenten-Endpunkt ein OAuth 2.0-Token für Endnutzer im Header Authorization erfordert (z. B. um einen auf Agent Runtime gehosteten A2A-Agenten aufzurufen oder ein Nutzertoken direkt an Ihren Agenten-Container zu übergeben). Weitere Informationen zur Funktionsweise von Authentifizierungs- und Autorisierungsheadern finden Sie unter So authentifiziert sich Gemini Enterprise bei Ihrem Agenten.
Wenn Ihr A2A-Agent den Agent Identity-Authentifizierungsmanager für dreibeiniges OAuth auf Toolebene verwendet (z. B. um im Namen des Nutzers auf MCP-Server oder APIs von Drittanbietern zuzugreifen), lesen Sie den Hilfeartikel Dreibeiniges OAuth mit dem Agent Identity-Authentifizierungsmanager konfigurieren.
So erstellen Sie eine OAuth-Client-ID:
Rufen Sie in der Google Cloud Console auf der Seite APIs & Dienste die Seite Anmeldedaten auf.
-
Wählen Sie das Projekt von Google Cloud aus, in dem sich die Datenquelle befindet, auf die der Agent zugreifen soll. Wählen Sie beispielsweise das Projekt aus, in dem das BigQuery-Dataset enthalten ist, das der Agent abfragen soll.
Klicken Sie auf Anmeldedaten erstellen und wählen Sie OAuth-Client-ID aus.
Wählen Sie unter Anwendungstyp die Option Webanwendung aus.
Fügen Sie im Abschnitt Autorisierte Weiterleitungs-URIs die folgenden URIs hinzu:
https://vertexaisearch.cloud.google.com/oauth-redirecthttps://vertexaisearch.cloud.google.com/static/oauth/oauth.html
Klicken Sie auf Erstellen.
Klicken Sie im Bereich OAuth-Client erstellt auf JSON herunterladen. Die heruntergeladene JSON-Datei enthält
Client ID,Authorization URI,Token URIundClient secretfür das ausgewählteGoogle Cloud -Projekt. Sie benötigen diese Informationen, um eine Autorisierungsressource zu erstellen.
Dreibeiniges OAuth mit dem Agent Identity-Authentifizierungsmanager konfigurieren (optional)
Wenn Ihr A2A-Agent mit dem Agent Development Kit (ADK) erstellt wurde und den Agent Identity-Authentifizierungsmanager für 3-legged OAuth (3LO) verwendet, kann er sich im Namen des angemeldeten Nutzers bei nachgelagerten MCP-Servern, Google Cloud-Diensten oder APIs von Drittanbietern authentifizieren.
Wenn ein Tool in Ihrem A2A-Agenten die Nutzereinwilligung erfordert, verwaltet Gemini Enterprise automatisch den clientseitigen 3LO-Workflow:
- Aufforderung zur Einwilligung: Wenn Ihr Agent eine
adk_request_credential-Toolunterbrechung (TASK_STATE_AUTH_REQUIRED) zurückgibt, fordert die Gemini Enterprise Web-App den Nutzer auf, sich anzumelden, und öffnet den Autorisierungs-URI des Authentifizierungsanbieters. - Nutzervalidierung und Tokenspeicherung: Nachdem der Nutzer seine Einwilligung erteilt hat, leitet der Authentifizierungsanbieter ihn an den Gemini Enterprise-Validierungsendpunkt (
https://vertexaisearch.cloud.google.com/validateUserId) weiter. Gemini Enterprise validiert den Sitzungsstatus und schließt die Anmeldedaten mit dem Agent Identity-Authentifizierungsmanager ab. - Unterhaltung fortsetzen: Gemini Enterprise sendet die abgeschlossene
adk_request_credential-Antwort an Ihren A2A-Agenten zurück. Dieser ruft das Zugriffstoken des Nutzers vom Authentifizierungsanbieter ab und ruft das Tool auf.
Da Gemini Enterprise die Einwilligungsaufforderung, den Validierungsendpunkt und die Fortsetzung der Unterhaltung übernimmt, müssen Sie keine benutzerdefinierte clientseitige UI-Anwendung implementieren.
Schritt 1: Dreibeinigen OAuth-Authentifizierungsanbieter einrichten
Folgen Sie der Anleitung unter Mit dreibeinigem OAuth mit Auth Manager authentifizieren, um die Agent Identity API (agentidentity.googleapis.com) zu aktivieren, Ihre OAuth-Clientanwendung zu konfigurieren und einen dreibeinigen OAuth-Authentifizierungsanbieter zu erstellen.
Wenn Sie Ihren OAuth-Client und Authentifizierungsanbieter für die Verwendung mit Gemini Enterprise konfigurieren, müssen Sie die folgenden Einstellungen festlegen:
Autorisierte Weiterleitungs-URIs: Fügen Sie in der OAuth-Clientkonfiguration den Callback-Weiterleitungs-URI des Authentifizierungsanbieters hinzu:
https://agentidentitycredentials.googleapis.com/v1/projects/<var>PROJECT_ID</var>/locations/<var>LOCATION</var>/authProviders/<var>AUTH_PROVIDER_NAME</var>/oauthcallbackWenn Sie denselben OAuth-Client für die Autorisierungsressource Ihres Gemini Enterprise-Agenten wiederverwenden (z. B. um Gemini Enterprise zu ermöglichen, einen auf Agent Runtime gehosteten A2A-Agenten aufzurufen), fügen Sie auch den Gemini Enterprise-Weiterleitungs-URI (
https://vertexaisearch.cloud.google.com/oauth-redirect) hinzu.Weiterleitungs-URI: Legen Sie den Weiterleitungs-URI (entweder als Standard-Weiterleitungs-URI beim Authentifizierungsanbieter oder als
continue_uriin Ihrem Agentencode) auf den Gemini Enterprise-Validierungsendpunkt fest:https://vertexaisearch.cloud.google.com/validateUserId
Schritt 2: Code für den A2A-Agenten konfigurieren
Wenn Sie einen ADK-Agenten erstellen und ihn mit A2aAgent für die Bereitstellung in der Agent Runtime verpacken, muss Ihr Agentencode die folgenden Anforderungen erfüllen:
- Erforderliche Paketversionen installieren: Nehmen Sie
a2a-sdk[http-server]>=1.0.0,google-cloud-aiplatform[agent_engines,adk]>=1.156.0undgoogle-adk[a2a,agent-identity,mcp]>2.7.1in Ihre Bereitstellungsanforderungen auf. continue_uriauf Gemini Enterprise festlegen: Legen Siecontinue_uriinGcpAuthProviderSchemeoderAgentRegistry.get_mcp_toolsetauf"https://vertexaisearch.cloud.google.com/validateUserId"fest (es sei denn, Sie haben es beim Authentifizierungsanbieter als Standard-Weiterleitungs-URI konfiguriert).GcpAuthProviderin der Runner-Builder-Funktion registrieren: Rufen SieCredentialManager.register_auth_provider(GcpAuthProvider())in der Funktion auf, die denRunnerim bereitgestellten Container-Worker-Prozess erstellt, anstatt nur auf der obersten Modulebene.- Integrierte
A2aAgentExecutorverwenden: Übergeben SieA2aAgentExecutor(runner=build_runner)(from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor) anA2aAgent. Verwenden Sie keine benutzerdefinierteAgentExecutor, die nurevent.is_final_response()prüft, daA2aAgentExecutorerforderlich ist, umadk_request_credential-Unterbrechungen in den A2A-AufgabenstatusTASK_STATE_AUTH_REQUIREDumzuwandeln. - A2A-Protokollversion
0.3inAgentCardeinbeziehen: Hängen Sie einenAgentInterfacemitprotocol_version=PROTOCOL_VERSION_0_3undprotocol_binding=TransportProtocol.HTTP_JSONanagent_card.supported_interfacesan, zusammen mit der Standard-1.0-Schnittstelle, damit Gemini Enterprise über A2A v0.3-Routen mit Ihrem Agenten kommunizieren kann.
ADK + A2A
Im folgenden Beispiel wird ein ADK-A2A-Agent konfiguriert, der GcpAuthProviderScheme mit McpToolset (oder AgentRegistry.get_mcp_toolset) verwendet, um sich im Namen des Nutzers bei einem MCP-Server zu authentifizieren:
from a2a.types import AgentInterface, AgentSkill from a2a.utils.constants import PROTOCOL_VERSION_0_3, PROTOCOL_VERSION_1_0, TransportProtocol from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor from google.adk.agents import LlmAgent from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme from google.adk.memory.in_memory_memory_service import InMemoryMemoryService from google.adk.runners import Runner from google.adk.sessions.in_memory_session_service import InMemorySessionService from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams from google.adk.tools.mcp_tool.mcp_toolset import McpToolset from vertexai.agent_engines.templates.a2a import A2aAgent, create_agent_card # Redirect URI for Gemini Enterprise user validation CONTINUE_URI = "https://vertexaisearch.cloud.google.com/validateUserId" auth_scheme = GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME", scopes=["OAUTH_SCOPE"], continue_uri=CONTINUE_URI, ) mcp_tools = McpToolset( connection_params=StreamableHTTPConnectionParams( url="https://YOUR_MCP_SERVER_URL" ), auth_scheme=auth_scheme, ) # Alternatively, if your MCP server is registered in Agent Registry # with an outbound auth provider binding, use AgentRegistry.get_mcp_toolset: # from google.adk.integrations.agent_registry import AgentRegistry # registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION") # mcp_tools = registry.get_mcp_toolset( # mcp_server_name="projects/PROJECT_ID/locations/LOCATION/mcpServers/MCP_SERVER_ID", # continue_uri=CONTINUE_URI, # ) adk_agent = LlmAgent( model="gemini-2.5-flash", name="AGENT_NAME", description="AGENT_DESCRIPTION", instruction="AGENT_INSTRUCTIONS", tools=[mcp_tools], ) def build_runner() -> Runner: # Register GcpAuthProvider inside the deployed worker process CredentialManager.register_auth_provider(GcpAuthProvider()) return Runner( app_name=adk_agent.name, agent=adk_agent, artifact_service=InMemoryArtifactService(), session_service=InMemorySessionService(), memory_service=InMemoryMemoryService(), ) agent_card = create_agent_card( agent_name="AGENT_DISPLAY_NAME", description="AGENT_DESCRIPTION", skills=[ AgentSkill( id="SKILL_ID", name="SKILL_NAME", description="SKILL_DESCRIPTION", tags=[], ) ], ) agent_card.supported_interfaces = [ AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_1_0, url="", ), AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_0_3, url="", ), ] a2a_agent = A2aAgent( agent_card=agent_card, agent_executor_builder=lambda: A2aAgentExecutor(runner=build_runner), )
ADK + A2A
Im folgenden Beispiel wird ein ADK-A2A-Agent konfiguriert, der AuthenticatedFunctionTool mit GcpAuthProviderScheme verwendet, um im Namen des Nutzers eine REST API eines Drittanbieters oder von Google Cloudaufzurufen:
from a2a.types import AgentInterface, AgentSkill from a2a.utils.constants import PROTOCOL_VERSION_0_3, PROTOCOL_VERSION_1_0, TransportProtocol from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor from google.adk.agents import LlmAgent from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService from google.adk.auth.auth_credential import AuthCredential from google.adk.auth.auth_tool import AuthConfig from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme from google.adk.memory.in_memory_memory_service import InMemoryMemoryService from google.adk.runners import Runner from google.adk.sessions.in_memory_session_service import InMemorySessionService from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool import httpx from vertexai.agent_engines.templates.a2a import A2aAgent, create_agent_card # Redirect URI for Gemini Enterprise user validation CONTINUE_URI = "https://vertexaisearch.cloud.google.com/validateUserId" auth_config = AuthConfig( auth_scheme=GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME", scopes=["OAUTH_SCOPE"], continue_uri=CONTINUE_URI, ) ) async def call_external_api(credential: AuthCredential, query: str) -> str: """Calls an external API using the end user's OAuth token.""" token = None if credential and credential.http and credential.http.credentials: token = credential.http.credentials.token if not token: return "Error: No authentication token available." async with httpx.AsyncClient() as client: response = await client.get( "https://YOUR_API_ENDPOINT", headers={"Authorization": f"Bearer {token}"}, params={"q": query}, ) response.raise_for_status() return response.text authenticated_tool = AuthenticatedFunctionTool( func=call_external_api, auth_config=auth_config, ) adk_agent = LlmAgent( model="gemini-2.5-flash", name="AGENT_NAME", description="AGENT_DESCRIPTION", instruction="AGENT_INSTRUCTIONS", tools=[authenticated_tool], ) def build_runner() -> Runner: # Register GcpAuthProvider inside the deployed worker process CredentialManager.register_auth_provider(GcpAuthProvider()) return Runner( app_name=adk_agent.name, agent=adk_agent, artifact_service=InMemoryArtifactService(), session_service=InMemorySessionService(), memory_service=InMemoryMemoryService(), ) agent_card = create_agent_card( agent_name="AGENT_DISPLAY_NAME", description="AGENT_DESCRIPTION", skills=[ AgentSkill( id="SKILL_ID", name="SKILL_NAME", description="SKILL_DESCRIPTION", tags=[], ) ], ) agent_card.supported_interfaces = [ AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_1_0, url="", ), AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_0_3, url="", ), ] a2a_agent = A2aAgent( agent_card=agent_card, agent_executor_builder=lambda: A2aAgentExecutor(runner=build_runner), )
Schritt 3: A2A-Agenten mit Agentenidentität bereitstellen und Zugriff gewähren
Stellen Sie Ihren
A2aAgentmitidentity_type=types.IdentityType.AGENT_IDENTITYin der Agent Runtime bereit:import vertexai from vertexai import types client = vertexai.Client( project="<var>PROJECT_ID</var>", location="<var>LOCATION</var>", http_options=dict(api_version="v1beta1"), ) remote_a2a_agent = client.agent_engines.create( agent=a2a_agent, config={ "display_name": "<var>AGENT_DISPLAY_NAME</var>", "identity_type": types.IdentityType.AGENT_IDENTITY, "requirements": [ "a2a-sdk[http-server]>=1.0.0", "google-cloud-aiplatform[agent_engines,adk]>=1.156.0", "google-adk[a2a,agent-identity,mcp]>2.7.1", "google-genai", "httpx", ], }, )Weisen Sie nach Abschluss der Bereitstellung dem SPIFFE-Hauptkonto des bereitgestellten KI-Agenten die Rolle Agent Identity User (
roles/agentidentity.user) für den Authentifizierungsanbieter zu:gcloud agent-identity auth-providers add-iam-policy-binding <var>AUTH_PROVIDER_NAME</var> \ --project="<var>PROJECT_ID</var>" \ --location="<var>LOCATION</var>" \ --role="roles/agentidentity.user" \ --member="principal://agents.global.org-<var>ORGANIZATION_ID</var>.system.id.goog/resources/aiplatform/projects/<var>PROJECT_NUMBER</var>/locations/<var>LOCATION</var>/reasoningEngines/<var>ENGINE_ID</var>"Ersetzen Sie Folgendes:
AUTH_PROVIDER_NAME: der Name Ihres Authentifizierungsanbieters.PROJECT_ID: die Projekt-ID.LOCATION: die Region, in der Ihr Authentifizierungsanbieter und Ihr Agent bereitgestellt werden (z. B.us-central1).ORGANIZATION_ID: Ihre Organisations-ID von Google Cloud.PROJECT_NUMBER: Die Nummer Ihres Projekts in Google Cloud .ENGINE_ID: Die Ressourcen-ID des bereitgestelltenreasoningEngines-Agenten.
Registrieren Sie den bereitgestellten A2A-Agenten bei Gemini Enterprise. Verwenden Sie dazu entweder A2A-Agenten bei Gemini Enterprise registrieren (Benutzerdefinierter Agent über A2A) oder A2A-Agenten aus der Agent Registry importieren (Benutzerdefinierter Agent über Agent Runtime). Da der Agent in der Agent Runtime gehostet wird, müssen Sie in Gemini Enterprise eine OAuth 2.0-Autorisierungsressource mit dem Bereich
https://www.googleapis.com/auth/cloud-platformkonfigurieren, damit Gemini Enterprise den Agent Runtime-Endpunkt aufrufen kann.
A2A-Agenten-Endpunkt schützen
Informationen zu den Authentifizierungsheadern, die Gemini Enterprise an Ihren A2A-Agenten sendet, finden Sie unter So authentifiziert sich Gemini Enterprise bei Ihrem Agenten. Beachten Sie beim Sichern Ihres Agenten-Endpunkts oder eines API-Gateways davor Folgendes:
- Sicherheitsschemas für Agentenkarten: Gemini Enterprise verwendet die Felder
securitySchemesundsecurityIhrer Agentenkarte nicht zur Authentifizierung bei Ihrem Agenten. - API-Schlüssel und benutzerdefinierte Header: Gemini Enterprise unterstützt das Sicherheitsschema
apiKeynicht und bietet keine Möglichkeit, statische API-Schlüssel oder andere benutzerdefinierte Headerwerte zu den Anfragen hinzuzufügen, die an Ihren Agenten gesendet werden. - Dienst-Agent-ID-Token: Gemini Enterprise sendet den Header
X-Serverless-Authorizationnur, wenn die URL Ihres Agenten eine Standard-Cloud Run-URL ist, die auf.run.appendet. Wenn Ihre Agenten-URL eine benutzerdefinierte Domain, einen Load Balancer oder ein API-Gateway verwendet, sendet Gemini Enterprise diesen Header nicht. - Endnutzer-Token: Wenn Sie OAuth 2.0 für Ihren Agenten konfigurieren, sendet Gemini Enterprise das Token des Endnutzers von Ihrem OAuth 2.0-Anbieter im Header
Authorization.
Agenten-Endpunkt mit Apigee schützen
Wenn Sie Ihren A2A-Agenten über einen Apigee-API-Proxy verfügbar machen, empfängt der Proxy das Endnutzertoken im Authorization-Header, aber nicht den X-Serverless-Authorization-Header. So sichern Sie den Proxy:
- Konfigurieren Sie OAuth 2.0 für die Endnutzerautorisierung für Ihren Agenten (entweder mit einer OAuth 2.0-Client-ID von Google Cloud oder einem OAuth 2.0-Drittanbieter) und geben Sie diese OAuth 2.0-Details an, wenn Sie den Agenten registrieren. Die Konfiguration von OAuth 2.0 ist erforderlich, wenn Sie einen Apigee API-Proxy sichern. Überspringen Sie den Autorisierungsschritt bei der Registrierung nicht.
- Legen Sie in Ihrer Agentenkarte
urlauf die URL Ihres Apigee API-Proxys fest. - Validieren Sie im API-Proxy das Endnutzer-Token im
Authorization-Header, bevor Sie die Anfrage an Ihren Agenten weiterleiten. Wählen Sie die Apigee-Richtlinie basierend auf dem Tokenformat aus, das Ihr OAuth 2.0-Anbieter ausgibt:- Drittanbieter von OAuth 2.0, die signierte JWT-Zugriffstokens ausstellen:
Verwenden Sie die VerifyJWT-Richtlinie, um die Tokensignatur mit dem öffentlichen JWKS-URI (JSON Web Key Set) Ihres Anbieters zu vergleichen und die Ansprüche des Ausstellers (
iss) und der Zielgruppe (aud) zu validieren. - Google OAuth 2.0 (
accounts.google.com): Google OAuth 2.0-Zugriffstokens (ya29...) sind opake Tokens und keine signierten JWTs. Verwenden Sie eine ServiceCallout-Richtlinie, umhttps://oauth2.googleapis.com/tokeninfoaufzurufen und die Felder „audience“ (aud) undscopezu prüfen.
- Drittanbieter von OAuth 2.0, die signierte JWT-Zugriffstokens ausstellen:
Verwenden Sie die VerifyJWT-Richtlinie, um die Tokensignatur mit dem öffentlichen JWKS-URI (JSON Web Key Set) Ihres Anbieters zu vergleichen und die Ansprüche des Ausstellers (
A2A-Agenten bei Gemini Enterprise registrieren
Sie können Ihren A2A-Agenten bei Gemini Enterprise entweder über dieGoogle Cloud Console oder die REST API registrieren. Dadurch wird der Agent für Nutzer in einer Gemini Enterprise-App verfügbar.
Console
So registrieren Sie einen A2A-Agenten über die Google Cloud Console:
Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf.
Klicken Sie auf den Namen der App, für die Sie den Agenten registrieren möchten.
Klicken Sie auf Agenten > Agenten hinzufügen.
Klicken Sie im Bereich Agenttyp auswählen für Benutzerdefinierter Agent über A2A auf Hinzufügen.
Geben Sie im Feld JSON-Agentenkarte die Details der Agentenkarte im JSON-Format ein. Eine vollständige Liste der verfügbaren Felder finden Sie in der offiziellen Spezifikation des Agent2Agent-Protokolls (A2A). Im folgenden Beispiel werden nur die erforderlichen Felder verwendet.
Beispiel:
{ "protocolVersion": "0.3", "name": "Hello World Agent", "description": "Just a hello world agent", "url": "https://example.com/myagent", "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=", "version": "1.0.0", "capabilities": { }, "skills": [ { "id": "data-analysis", "name": "Data Analysis", "description": "Data analysis", "tags": [] } ], "defaultInputModes": [ "text/plain" ], "defaultOutputModes": [ "text/plain" ] }Klicken Sie auf Agentendetails ansehen > Weiter.
Schließen Sie die Einrichtung mit einer der folgenden Methoden ab:
- Wenn Sie nicht möchten, dass der Agent in Ihrem Namen auf Google Cloud -Ressourcen zugreift, und Ihr Agenten-Endpunkt keinen
Authorization-Header erfordert, klicken Sie auf Überspringen und beenden, um diesen Schritt zu überspringen. - Wenn Sie 3LO mit dem Auth Manager konfiguriert haben, klicken Sie auf Überspringen und beenden. Der Agent fordert dann dynamisch Zugriff an.
Wenn Sie 3LO nicht mit dem Auth Manager konfiguriert haben oder Ihr Agenten-Endpunkt einen
Authorization-Header erfordert (z. B. beim Sichern eines Apigee API-Proxys), gehen Sie so vor:Geben Sie die Client-ID, den Clientschlüssel, den Autorisierungs-URI und den Token-URI ein, die Sie im Abschnitt OAuth 2.0 für die Endnutzerautorisierung konfigurieren (optional) generiert haben.
Geben Sie die Bereiche ein.
Klicken Sie auf Beenden.
- Wenn Sie nicht möchten, dass der Agent in Ihrem Namen auf Google Cloud -Ressourcen zugreift, und Ihr Agenten-Endpunkt keinen
REST
So registrieren Sie einen A2A-Agenten über die REST API:
Autorisierungsressource zu Gemini Enterprise hinzufügen (optional)
Wenn der KI-Agent im Namen eines Nutzers auf Ressourcen von Google Cloud zugreifen muss, führen Sie den folgenden Befehl aus, um die Autorisierungsressource, die Sie im Abschnitt Autorisierungsdetails konfigurieren (optional) erstellt haben, bei Gemini Enterprise zu registrieren:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
-d '{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID",
"serverSideOauth2": {
"clientId": "OAUTH_CLIENT_ID",
"clientSecret": "OAUTH_CLIENT_SECRET",
"authorizationUri": "OAUTH_AUTH_URI",
"tokenUri": "OAUTH_TOKEN_URI"
}
}'
Ersetzen Sie Folgendes:
PROJECT_ID: die Projekt-ID.PROJECT_NUMBER: Die Nummer Ihres Projekts von Google Cloud .ENDPOINT_LOCATION: die Multiregion für Ihre API-Anfrage. Geben Sie einen der folgenden Werte an:usfür die Multiregion „USA“eufür die Multiregion „EU“globalfür den Standort „Global“
LOCATION: die Multiregion Ihres Datenspeichers: global, us oder euAUTH_ID: die ID der Autorisierungsressource. Dies ist eine beliebige alphanumerische ID, die Sie definieren. Sie müssen später auf diese ID verweisen, wenn Sie einen Agenten registrieren, der OAuth-Unterstützung erfordert.OAUTH_CLIENT_ID: die OAuth 2.0-Client-ID, die Sie beim Erstellen der OAuth-Anmeldedaten erhalten haben.OAUTH_CLIENT_SECRET: der OAuth 2.0-Clientschlüssel, den Sie beim Erstellen der OAuth-Anmeldedaten erhalten haben.OAUTH_AUTH_URI: der Autorisierungs-URI. Wenn Sie Ihre App autorisieren möchten, erstellen Sie einen bestimmten Autorisierungs-URI mit den Details aus der JSON-Datei mit den OAuth-Anmeldedaten. Kopieren Sie die folgende Vorlage und ersetzen Sie die Platzhalter durch Ihre spezifischen Werte.
https://accounts.google.com/o/oauth2/v2/auth?client_id=OAUTH_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
YOUR_CUSTOM_SCOPES: Sie können die erforderlichen Bereiche hinzufügen. Der folgende OAuth-Bereichsstring fordert beispielsweise Lesezugriff auf Google Drive und Google Docs an.scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly
OAUTH_TOKEN_URI: der Token-URI, den Sie beim Erstellen der OAuth-Anmeldedaten erhalten haben.
Weitere Informationen zu Autorisierungs-URI-Parametern.
Prüfen Sie die folgenden Felder, um sicherzustellen, dass der URI ordnungsgemäß funktioniert:
| Parameter | Wert oder Aktion |
|---|---|
client_id |
Ersetzen Sie den Platzhalter durch den client_id, der in der heruntergeladenen JSON-Datei enthalten ist. |
redirect_uri |
Nicht ändern. Muss https://vertexaisearch.cloud.google.com/static/oauth/oauth.html lauten. |
scope |
Listen Sie die Google API-Bereiche auf, auf die Ihre App im Namen des Nutzers zugreifen muss. Wenn Sie beispielsweise Zugriff auf BigQuery gewähren möchten, verwenden Sie den Bereich Wenn Sie mehrere Bereiche verwenden, trennen Sie sie durch ein Leerzeichen, das in der URL zu |
include_granted_scopes |
Muss true lauten. |
response_type |
Sie müssen code sein, um einen Autorisierungscode zu erhalten. |
access_type |
Legen Sie offline fest, damit Sie ein Aktualisierungstoken erhalten. |
prompt |
Legen Sie consent fest, damit dem Nutzer immer ein Zustimmungsbildschirm angezeigt wird. |
A2A-Agenten registrieren
Verwenden Sie zum Erstellen und Registrieren eines Agenten mit Gemini Enterprise die Methode agents.create. Im folgenden Befehl werden nur die erforderlichen Felder verwendet. Eine vollständige Liste der verfügbaren Felder finden Sie in der offiziellen Spezifikation des Agent2Agent-Protokolls (A2A).
Führen Sie diesen Befehl aus, um Ihren A2A-Agenten bei Gemini Enterprise zu registrieren:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents \
-d '
{
"name": "AGENT_NAME",
"displayName": "AGENT_DISPLAY_NAME",
"description": "AGENT_DESCRIPTION",
"a2aAgentDefinition": {
"jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
},
"authorizationConfig": {
"agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
}
}
'
Ersetzen Sie Folgendes:
ENDPOINT_LOCATION: die Multiregion für Ihre API-Anfrage. Geben Sie einen der folgenden Werte an:usfür die Multiregion „USA“eufür die Multiregion „EU“globalfür den Standort „Global“
LOCATION: Der multiregionale Standort Ihres Datenspeichers: global, us oder eu.PROJECT_ID: Die Projekt-ID.APP_ID: Die ID der App, mit der Sie den Agenten registrieren möchten.AGENT_NAME: die eindeutige Kennung für den Agenten.AGENT_DISPLAY_NAME: Der Name des Agenten, der in der Web-App angezeigt wird.AGENT_DESCRIPTION: Die Beschreibung der Funktionen des Agenten.PROTOCOLVERSION: Die Version des A2A-Protokolls, die der Agent unterstützt. Weitere Informationen zu den unterstützten Versionen finden Sie in den A2A-Versionshinweisen.AGENT_URL: Die Endpunkt-URL des Agenten.AGENT_VERSION: die Version des Agenten.INPUT_MODE: der Standard-Eingabemedientyp. Zum Beispiel application/json oder text/plain.OUTPUT_MODE: der Standard-Ausgabemedientyp. Zum Beispiel text/plain" oder image/png.CAPABILITIES: ein JSON-Objekt mit unterstützten A2A-Funktionen. Beispiel: \"streaming\": true oder \"pushNotifications\": falseSKILLS: eine Liste der AgentSkill-Objekte, die der Agent anbietet.authorizationConfig: Wenn Sie die Autorisierungsdetails erhalten haben und der Agent im Namen des Nutzers auf Google Cloud -Ressourcen zugreifen soll, fügen Sie das Feld authorization_config in Ihre JSON-Ressource ein.
AUTH_ID: Der Wert, den Sie für AUTH_ID im Abschnitt Autorisierungsressource zu Gemini Enterprise hinzufügen verwendet haben.
Informationen zum Autor und Kontaktdaten für einen KI-Agenten anzeigen (optional)
Standardmäßig wird für einen von Ihnen registrierten A2A-Agenten in Gemini Enterprise kein Autor angezeigt. Wenn Sie angeben möchten, wer den Agenten erstellt hat und an wen sich Nutzer wenden können, fügen Sie die Erweiterung für Agentenmetadaten dem Feld capabilities.extensions der JSON-Datei der Agentenkarte hinzu, die Sie zum Registrieren oder Aktualisieren des Agenten verwenden:
{
"capabilities": {
"extensions": [
{
"uri": "https://www.googleapis.com/gemini-enterprise/a2a/extensions/agent_metadata/v1",
"params": {
"authorName": "Example Team",
"contactEmail": "agent-support@example.com"
}
}
]
}
}
Behalten Sie die anderen Felder der Agentenkarte aus dem Registrierungsbeispiel neben capabilities bei. In der REST API ist die Erweiterung Teil des maskierten jsonAgentCard-Strings.
Das Feld params unterstützt die folgenden Werte: Beide sind optional.
| Parameter | Beschreibung |
|---|---|
authorName |
Der Name der Person, des Teams oder des Unternehmens, die oder das den KI-Agenten erstellt hat. In der KI-Agentengalerie wird er auf der Karte des KI-Agenten als Von AUTHOR_NAME und im Dialogfeld KI-Agenteninfo als Autor angezeigt. In der Galerie wird dieser Name nur angezeigt, wenn der KI-Agent keinen eigenen Inhabernamen hat. Namen, die das Wort „Google“ enthalten, werden nicht angezeigt, damit sie nicht mit von Google erstellten Agenten verwechselt werden können. |
contactEmail |
Eine E-Mail-Adresse, unter der Nutzer den Autor erreichen können. Im Dialogfeld Agenteninformationen wird er als Kontakt angezeigt. |
Jeder Wert muss ein String mit maximal 256 Zeichen sein und contactEmail muss eine gültige E-Mail-Adresse sein. Gemini Enterprise ignoriert Werte, die diese Anforderungen nicht erfüllen. Gemini Enterprise überprüft weder den Namen des Autors noch die Kontakt-E-Mail-Adresse.
Mit einer App verbundene Agenten auflisten
Im folgenden Codebeispiel wird gezeigt, wie Sie die Details aller mit Ihrer App verbundenen Agenten abrufen können:
REST
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"
Ersetzen Sie die Variablen durch folgende Werte:
- ENDPOINT_LOCATION: die Multiregion für Ihre API-Anfrage. Geben Sie einen der folgenden Werte an:
usfür die Multiregion „USA“eufür die Multiregion „EU“globalfür den Standort „Global“
global, us oder eu.Wenn Ihr Agent nicht von Google vorab erstellt wurde, enthält die Antwort in den ersten Zeilen das Feld name. Der Wert dieses Felds enthält die Agenten-ID am Ende des Pfads. In der folgenden Antwort lautet die Agenten-ID beispielsweise 12345678901234567890:
{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}
A2A-Agentendetails ansehen
Im folgenden Codebeispiel wird gezeigt, wie Sie die Details eines Agenten abrufen können, der bei Gemini Enterprise registriert wurde:
REST
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"
Ersetzen Sie die Variablen durch folgende Werte:
- ENDPOINT_LOCATION: die Multiregion für Ihre API-Anfrage. Geben Sie einen der folgenden Werte an:
usfür die Multiregion „USA“eufür die Multiregion „EU“globalfür den Standort „Global“
global, us oder eu.A2A-Agenten aktualisieren
Sie können die Details eines vorhandenen A2A-Agenten, der bei Gemini Enterprise registriert ist, entweder über die Google Cloud Console oder die REST API ändern.
Console
So aktualisieren Sie einen A2A-Agenten über die Google Cloud Console:
Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf.
Klicken Sie auf den Namen der App, die den Agenten enthält, den Sie aktualisieren möchten.
Klicken Sie auf Agenten.
Klicken Sie auf den Namen des (benutzerdefinierten) A2A-Agenten, den Sie aktualisieren möchten, und dann auf Bearbeiten.
Aktualisieren Sie im Feld JSON-Agentenkarte die Details der Agentenkarte im JSON-Format. Eine vollständige Liste der verfügbaren Felder finden Sie in der offiziellen Spezifikation des Agent2Agent-Protokolls (A2A). Im folgenden Beispiel werden nur die erforderlichen Felder verwendet.
Beispiel:
{ "protocolVersion": "0.3", "name": "Hello World Agent", "description": "Just a hello world agent", "url": "https://example.com/myagent", "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=", "version": "1.1.0", "capabilities": { }, "skills": [ { "id": "data-analysis", "name": "Data Analysis", "description": "Data analysis", "tags": [] } ], "defaultInputModes": [ "text/plain" ], "defaultOutputModes": [ "text/plain" ] }Klicken Sie auf Speichern.
REST
Verwenden Sie die Methode agents.patch, um die Details eines A2A-Agenten zu aktualisieren, der bei Gemini Enterprise registriert ist. Im folgenden Befehl werden nur die erforderlichen Felder verwendet. Eine vollständige Liste der verfügbaren Felder finden Sie in der offiziellen Spezifikation des Agent2Agent-Protokolls (A2A).
Führen Sie diesen Befehl aus, um Ihren A2A-Agenten bei Gemini Enterprise zu aktualisieren:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID \
-d '
{
"name": "AGENT_NAME",
"displayName": "AGENT_DISPLAY_NAME",
"description": "AGENT_DESCRIPTION",
"a2aAgentDefinition": {
"jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
},
"authorizationConfig": {
"agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
}
}
'
Ersetzen Sie Folgendes:
ENDPOINT_LOCATION: die Multiregion für Ihre API-Anfrage. Geben Sie einen der folgenden Werte an:usfür die Multiregion „USA“eufür die Multiregion „EU“globalfür den Standort „Global“
LOCATION: Der multiregionale Standort Ihres Datenspeichers: global, us oder eu.PROJECT_ID: Die Projekt-ID.APP_ID: Die ID der Anwendung, mit der Sie den Agenten registrieren möchten.AGENT_NAME: Die eindeutige Kennung für den Agenten.AGENT_DISPLAY_NAME: Der Name des Agenten, der in der Web-App angezeigt wird.AGENT_DESCRIPTION: Die Beschreibung der Funktionen des Agenten.PROTOCOLVERSION: Die Version des A2A-Protokolls, die der Agent unterstützt. Weitere Informationen zu den unterstützten Versionen finden Sie in den A2A-Versionshinweisen.AGENT_URL: Die Endpunkt-URL des Agenten.AGENT_VERSION: die Version des Agenten.INPUT_MODE: der Standard-Eingabemedientyp. Zum Beispiel application/json oder text/plain.OUTPUT_MODE: der Standard-Ausgabemedientyp. Zum Beispiel text/plain oder image/png.CAPABILITIES: ein JSON-Objekt mit unterstützten A2A-Funktionen. Beispiel: \"streaming\": true oder \"pushNotifications\": falseSKILLS: eine Liste der AgentSkill-Objekte, die der Agent anbietet.authorizationConfig: Wenn Sie die Autorisierungsdetails erhalten haben und der Agent im Namen des Nutzers auf Google Cloud -Ressourcen zugreifen soll, fügen Sie das Feld authorization_config in Ihre JSON-Ressource ein.
AUTH_ID: Der Wert, den Sie für AUTH_ID im Abschnitt Autorisierungsressource zu Gemini Enterprise hinzufügen verwendet haben.
A2A-Agenten löschen
Im folgenden Codebeispiel wird gezeigt, wie Sie einen Agenten löschen, der mit Ihrer Anwendung verbunden ist:
REST
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"
Ersetzen Sie die Variablen durch folgende Werte:
- ENDPOINT_LOCATION: die Multiregion für Ihre API-Anfrage. Geben Sie einen der folgenden Werte an:
usfür die Multiregion „USA“eufür die Multiregion „EU“globalfür den Standort „Global“
global, us oder eu.Nächste Schritte
- Verwenden Sie den Agenten, den Sie bei Gemini Enterprise in der Web-App registriert haben.