Auf dieser Seite wird beschrieben, wie Administratoren ADK-Agenten aus Agent Runtime für die Verwendung in der Gemini Enterprise Web-App registrieren.
Für ADK-Agenten, die in der Agent Runtime bereitgestellt werden, können Sie einen einzigen Agents CLI in Agent Platform-Befehl verwenden, um die Agenten bei Gemini Enterprise zu registrieren.
Wenn Sie ADK-Agenten, die in der Agent Runtime gehostet werden, bei einer Gemini Enterprise-App registrieren und diese Agenten Endnutzern in der Gemini Enterprise-Web-App zur Verfügung stellen, gilt Folgendes:
Der Agent Runtime-Dienst verarbeitet die Agent-Anfragen.
Es gelten die Bedingungen für die ML-Verarbeitung in Agent Runtime. Weitere Informationen finden Sie unter Einschränkungen für Agent Runtime.
In der folgenden Tabelle wird beschrieben, wie ADK-Agenten verwaltet werden, um eine sichere und kontrollierte Bereitstellung und Nutzung zu gewährleisten.
| Agenten-Governance | Beschreibung |
|---|---|
| Sichere Kommunikation | Die Verbindung zwischen Agent Runtime und Gemini Enterprise ist mit VPC Service Controls (VPC-SC) konform, was einen sicheren Datenaustausch gewährleistet. |
| Projektübergreifende Agentenunterstützung | Sie können ADK-Agenten verbinden, die in einer anderen Google Cloudgehostet werden. Gemini Enterprise verwendet für diese projektübergreifenden Verbindungen das sichere private Netzwerk von Google Cloud. Weitere Informationen finden Sie unter Projektübergreifenden ADK-Agent-Zugriff konfigurieren. |
| Personalisierte Interaktionen | ADK-Agenten erhalten die E‑Mail-Adresse des Nutzers von Gemini Enterprise. So können Agenten einzelne Nutzer erkennen und personalisierte Antworten basierend auf ihrer Identität und ihren Berechtigungen geben. |
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 ADK-Agent, der in der Agent Runtime gehostet wird. Weitere Informationen finden Sie unter Übersicht über das Agent Development Kit.
- Wenn Sie keinen Agenten haben, folgen Sie der Anleitung im
adk-samples-GitHub-Repository, um einenfun_facts-Agenten in Agent Runtime bereitzustellen. Anschließend können Sie den Agenten bei Gemini Enterprise registrieren.
- Wenn Sie keinen Agenten haben, folgen Sie der Anleitung im
Wenn Ihr ADK-Agent in einem anderen Google Cloud -Projekt als Ihre Gemini Enterprise-App gehostet wird, müssen Sie die erforderlichen Berechtigungen erteilen. Weitere Informationen finden Sie unter Berechtigungen für projektübergreifenden ADK-Agent-Zugriff gewähren.
Autorisierungsdetails konfigurieren (optional)
So rufen Sie die Autorisierungsdetails ab:
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.
ADK-Agenten bei Gemini Enterprise registrieren
Sie können Ihren ADK-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 ADK-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. Die Seite Agenten wird angezeigt.
Klicken Sie auf Agent hinzufügen. Der Bereich Agent hinzufügen wird angezeigt.
Klicken Sie für Benutzerdefinierter KI-Agent über Agent Runtime auf Hinzufügen. Die Seite Autorisierungen wird angezeigt.
Wenn der KI-Agent in Ihrem Namen auf Ressourcen von Google Cloud zugreifen soll, muss jede Ressource autorisiert werden. So richten Sie eine Autorisierung für eine einzelne Ressource ein:
Klicken Sie auf Autorisierung hinzufügen.
Geben Sie einen eindeutigen Wert für Autorisierungsname ein. Eine ID wird basierend auf dem Namen generiert und kann später nicht mehr geändert werden.
Geben Sie die Werte, die Sie unter Autorisierungsdetails konfigurieren (optional) generiert haben, in die folgenden Felder ein:
Geben Sie den Wert in das Feld Client-ID ein.
Geben Sie den Wert in das Feld Clientschlüssel ein.
Geben Sie den Wert in das Feld Token-URI ein.
Geben Sie den Wert in das Feld Autorisierungs-URI ein. Erstellen Sie den Autorisierungs-URI mit den Details aus der JSON-Datei mit Ihren 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=YOUR_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
Klicken Sie auf Fertig.
Klicken Sie auf Weiter.
So konfigurieren Sie Ihren KI-Agenten:
Geben Sie einen Namen in das Feld KI-Agentenname ein. Dieser Wert wird in der Gemini Enterprise Web-App als Anzeigename Ihres KI-Agenten angezeigt.
Geben Sie im Feld KI-Agenten beschreiben eine Beschreibung ein. Dieser Wert wird von einem LLM verwendet, um festzulegen, ob Ihr KI-Agent zum Beantworten einer Nutzeranfrage aufgerufen werden soll.
Geben Sie den Ressourcenpfad für die Agent Runtime ein. Der Ressourcenpfad hat dieses Format:
projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID
Weitere Informationen zum Auflisten der in Agent Runtime gehosteten Agenten und zum Abrufen des Ressourcenpfads finden Sie unter Bereitgestellte Agenten auflisten.
Klicken Sie auf Erstellen.
REST
So registrieren Sie einen ADK-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. Mit dem folgenden OAuth-Bereichsstring wird beispielsweise Lesezugriff 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 ordnungsgemäß funktioniert:
| Parameter | Wert oder Aktion |
|---|---|
client_id |
Ersetzen Sie 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. |
ADK-Agenten registrieren
In diesem Codebeispiel wird gezeigt, wie Sie Ihre ADK-Agenten 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_ID/locations/global/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
-d '{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"icon": {
"uri": "ICON_URI"
},
"adkAgentDefinition": {
"provisionedReasoningEngine": {
"reasoningEngine": "projects/PROJECT_ID/locations/RESOURCE_LOCATION/reasoningEngines/RESOURCE_ID"
}
},
"authorizationConfig": {
"toolAuthorizations": [
"projects/PROJECT_NUMBER/locations/global/authorizations/AUTH_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“
PROJECT_ID: die ID Ihres Projekts in Google Cloud .
PROJECT_NUMBER: Die Nummer Ihres Projekts in Google Cloud .
APP_ID: die eindeutige Kennung für die Gemini Enterprise-App.
DESCRIPTION: die Beschreibung des KI-Agenten, die in Gemini Enterprise angezeigt wird.
ICON_URI: der öffentliche URI des Symbols, das neben dem Namen des Agenten angezeigt werden soll. Alternativ können Sie Inhalte von Base64-codierten Bilddateien übergeben. Verwenden Sie in diesem Fall
icon.content.RESOURCE_ID: die ID des Agent Runtime-Endpunkts, an dem der ADK-Agent bereitgestellt wird. Weitere Informationen dazu, wie Sie die in Agent Runtime gehosteten Agenten auflisten und ihre Ressourcen-ID abrufen, finden Sie unter Bereitgestellte Agenten auflisten.
RESOURCE_LOCATION: der Cloud-Standort des Agent Runtime-Endpunkts. Weitere Informationen finden Sie unter Agent Runtime-Standort.
authorization_config: Wenn Sie die Autorisierungsdetails erhalten haben und der Agent im Namen des Nutzers auf Ressourcen von Google Cloud zugreifen soll, fügen Sie das Feldauthorization_configin Ihre JSON-Ressource ein.AUTH_ID: Der Wert, den Sie für AUTH_ID im Abschnitt Autorisierungsdetails konfigurieren verwendet haben.
KI-Agenten für Nutzer freigeben
Informationen dazu, wie Sie Nutzern Zugriff auf einen Agenten über die Gemini Enterprise-Webanwendung gewähren, finden Sie unter Agenten freigeben.
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",
...
}
ADK-Agentendetails ansehen
Im folgenden Codebeispiel wird gezeigt, wie Sie die Details eines KI-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.ADK-Agenten aktualisieren
Sie können die Details eines vorhandenen Agenten, der bei Gemini Enterprise registriert ist, entweder über die Google Cloud Console oder die REST API ändern.
Console
So aktualisieren Sie den 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 Agent Runtime-Agenten, den Sie aktualisieren möchten, und dann auf Bearbeiten.
Aktualisieren Sie den Anzeigenamen, die Beschreibung oder die Reasoning Engine von Agent Runtime.
Der Ressourcenpfad hat dieses Format:
projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID
Weitere Informationen zum Auflisten der in Agent Runtime gehosteten Agenten und zum Abrufen des Ressourcenpfads finden Sie unter Bereitgestellte Agenten auflisten.
Klicken Sie auf Speichern.
REST
Sie können alle Felder bei der Registrierung des KI-Agenten aktualisieren. Die folgenden Felder müssen jedoch aktualisiert werden:
displayNamedescriptionreasoningEngineIn diesem Codebeispiel wird gezeigt, wie Sie die Registrierung eines vorhandenen ADK-Agenten aktualisieren:
curl -X PATCH \ -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/AGENT_RESOURCE_NAME" \ -d '{ "displayName": "DISPLAY_NAME", "description": "DESCRIPTION", "adkAgentDefinition": { "provisionedReasoningEngine": { "reasoningEngine": "projects/PROJECT_ID/locations/RESOURCE_LOCATION/reasoningEngine s/RESOURCE_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“
PROJECT_ID: die ID Ihres Google Cloud -Projekts.
AGENT_RESOURCE_NAME: Der Ressourcenname des registrierten KI-Agenten, der aktualisiert werden soll.
DISPLAY_NAME: Der nutzerfreundliche Name für Ihren KI-Agenten, der in Gemini Enterprise angezeigt wird.
DESCRIPTION: erforderlich. Eine kurze Beschreibung der Funktion Ihres KI-Agenten, die Nutzern in Gemini Enterprise angezeigt wird.
RESOURCE_LOCATION: der Cloud-Standort des Agent Runtime-Endpunkts. Weitere Informationen finden Sie unter Agent Runtime-Standort.
RESOURCE_ID: die ID des Agent Runtime-Endpunkts, an dem der ADK-Agent bereitgestellt wird. Weitere Informationen dazu, wie Sie die in Agent Runtime gehosteten Agenten auflisten und ihre Ressourcen-ID abrufen, finden Sie unter Bereitgestellte Agenten auflisten.
ADK-Agent löschen
Im folgenden Codebeispiel wird gezeigt, wie Sie einen KI-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.Agent Runtime-Standort
Wenn Sie einen Agenten registrieren oder aktualisieren, muss der Standort der Agent Runtime mit dem Standort Ihrer Gemini Enterprise-App kompatibel sein. Nicht übereinstimmende Standorte führen zu einem Fehler.
In der folgenden Tabelle finden Sie die Kompatibilitätsanforderungen:
| Standort der Gemini Enterprise-App | Zulässige Agent Runtime-Standorte |
|---|---|
global |
Beliebige unterstützte Google Cloud -Region |
us |
Beliebige Region, die mit us- beginnt, z. B. us-central1 oder us-east4 |
eu |
Beliebige Region, die mit europe- beginnt, z. B. europe-west1 oder europe-west3 |
Best Practices für Leistung und Zuverlässigkeit
Wenn Sie ADK-Agenten ausführen, die in der Agent Runtime in Gemini Enterprise gehostet werden, sollten Sie die folgenden Best Practices beachten, um die Antwortlatenz zu minimieren und Zeitüberschreitungen bei Anfragen zu vermeiden:
- Sequenzielle Multi-Agenten-Hops und redundante Zusammenfassungen minimieren: Jede zusätzliche Übergabe an einen Sub-Agenten oder jeder Tool-Roundtrip erhöht die Latenz der Modellinferenz für die Runde. Vermeiden Sie tiefe sequenzielle Agentenketten und umschließen Sie Sub-Agenten mit
AgentTool(..., skip_summarization=True), wenn der übergeordnete Agent keinen zusätzlichen Modelldurchlauf ausführen muss, um die Ausgabe eines Sub-Agenten noch einmal zusammenzufassen. - Laufzeitskalierung und Nebenläufigkeit für Multi-User-Arbeitslasten konfigurieren: Um Verzögerungen beim Kaltstart, Warteschlangen für Anfragen und Abstürze aufgrund von Speichermangel (
OOM) zu vermeiden, wenn mehrere Nutzer gleichzeitig Ihren Agenten abfragen, konfigurieren Siemin_instances,resource_limits(cpuundmemory) undcontainer_concurrency, wenn Sie in Agent Runtime bereitstellen. Weitere Informationen finden Sie unter Leistung der Agent Runtime optimieren und skalieren. - Übereinstimmende Paketversionen zwischen lokalem Build und Cloud-Laufzeit anpinnen: Wenn Sie einen Agenten in Agent Runtime bereitstellen, pinnen Sie genau dieselben Versionen von
google-adk,google-cloud-aiplatformundcloudpicklein Ihrer Bereitstellungslisterequirementsan, die Sie in Ihrer lokalen Build-Umgebung verwenden, um Deserialisierungsaufwand und Initialisierungsverzögerungen zu vermeiden. - Verwenden Sie den
global-Endpunkt für Modellaufrufe und Wiederholungsversuche für gebundene Tools: Wenn Ihr ADK-Agent Gemini-Modelle in Vertex AI aufruft, verwenden Sie denglobal-Endpunkt (oder den bereitgestellten Durchsatz), um regionale Kapazitätskonflikte zu reduzieren. Konfigurieren Sie explizite Verbindungszeitlimits und begrenzte Wiederholungsversuche für externe Toolaufrufe, damit langsame Downstream-Abhängigkeiten keine kaskadierenden Zeitlimits für Turns verursachen.