Das Agent2Agent-Protokoll (A2A) ist ein offenes Kommunikationsprotokoll und eine universelle Sprache für Agenten. Das Protokoll ermöglicht es Agenten von verschiedenen Entwicklern und Plattformen, einander zu finden, zusammenzuarbeiten und Aufgaben sicher zu 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-Administrator.
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-Streamingmechanismus.
Wenn Sie A2A v1.0.0 oder höher verwenden, können Sie mit den vom SDK bereitgestellten Kompatibilitätspaketen dafür sorgen, dass Ihr Agent mit dem früheren Mechanismus funktioniert, z. B. mit dem
a2acompat/a2av0-Paket für Go oder dema2a.compat.v0_3-Paket für Python.
Autorisierungsdetails konfigurieren (optional)
Bei A2A-Agents können Sie mit den OAuth 2.0-Anmeldedaten den Endnutzerzugriff auf A2A-Agents steuern. Wenn der Agent jedoch in Cloud Run ausgeführt wird und Identity and Access Management für die Zugriffssteuerung verwendet, sind die OAuth 2.0-Anmeldedaten nicht erforderlich.
Rufen Sie in der Google Cloud Console auf der Seite APIs & Dienste die Seite Anmeldedaten auf.
-
Wählen Sie das Google Cloud -Projekt aus, das die Datenquelle enthält, 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.
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 der Agent in Ihrem Namen auf Google Cloud -Ressourcen zugreifen soll, gehen Sie so vor:
Geben Sie die Client-ID, den Clientschlüssel, den Autorisierungs-URI und den Token-URI ein, die Sie im Abschnitt Autorisierungsdetails abrufen 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, klicken Sie auf Überspringen und beenden.
REST
So registrieren Sie einen A2A-Agenten über die REST API:
Autorisierungsressource zu Gemini Enterprise hinzufügen (optional)
Wenn der Agent im Namen eines Nutzers auf Google Cloud -Ressourcen 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. Um Ihre App zu autorisieren, 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: Hier können Sie die benötigten Bereiche hinzufügen. Mit dem folgenden OAuth-Bereichsstring wird beispielsweise schreibgeschützter Zugriff auf Google Drive und Google Docs angefordert.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 korrekt funktioniert:
| Parameter | Wert oder Aktion |
|---|---|
client_id |
Ersetzen Sie client_id durch den Wert, der in der heruntergeladenen JSON-Datei enthalten ist. |
redirect_uri |
Nicht ändern. Muss https://vertexaisearch.cloud.google.com/static/oauth/oauth.html sein. |
scope |
Geben Sie die Google API-Bereiche an, 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, um sicherzustellen, dass 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.
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.