In dieser Anleitung wird beschrieben, wie Sie einen A2A-Agenten, der mit dem Agent Development Kit (ADK) und der A2UI-Erweiterung erstellt wurde, in Cloud Run bereitstellen. Außerdem erfahren Sie, wie Sie den bereitgestellten Agenten bei Gemini Enterprise registrieren.
In diesem Beispiel wird öffentlich verfügbarer Beispielcode verwendet. Der Beispielcode für diese Anleitung hat die folgende Ordnerstruktur.
Ordnerstruktur der Anleitung
Das Projekt hat die folgende Ordnerstruktur:
| Datei/Verzeichnis | Beschreibung |
|---|---|
/samples/community/agent/adk/gemini_enterprise/v0_9 |
Verzeichnis mit Beispielkonfigurationen und Daten für diese Anleitung. |
__init__.py |
Kennzeichnet das Verzeichnis als Python-Paket. |
__main__.py |
Der Einstiegspunkt, um den Agenten lokal auszuführen. |
agent.py |
Definiert den KI-Agenten, seine Fähigkeiten und sein Verhalten. |
agent_executor.py |
Verwaltet den Ausführungsablauf und die Toolinteraktionen. |
deploy.sh |
Skript zum Erstellen und Bereitstellen des KI-Agenten in Cloud Run. |
examples/ |
Verzeichnis mit Beispielen für Komponentenvorlagen. |
gemini_enterprise_composite_catalog.json |
Komponentenkatalog, in dem Standard-Material- und benutzerdefinierte Gemini Enterprise-Komponenten definiert sind. |
main.py |
Der Haupteinstiegspunkt der Anwendung (FastAPI-Anwendung). |
prompt_builder.py |
Hilfsprogramm zum Erstellen von Prompts für das Modell. |
pyproject.toml |
Projektkonfiguration und Abhängigkeiten. |
examples/0.9/material_table_orders.json |
Beispiel-UI-Vorlage mit dem Layout und den simulierten Daten für die Demo der letzten Bestellungen. |
tools.py |
Definiert die Tools (Funktionen), die der KI-Agent verwenden kann. |
Hinweis
Bevor Sie beginnen, benötigen Sie Folgendes:
Die Rolle Discovery Engine Admin.
Eine vorhandene Gemini Enterprise-App. Informationen zum Erstellen einer App finden Sie unter App erstellen.
Klonen Sie das Repository und rufen Sie das Beispielverzeichnis
v0_9auf:git clone https://github.com/a2ui-project/a2ui.git cd a2ui/samples/community/agent/adk/gemini_enterprise/v0_9
APIs aktivieren
Aktivieren Sie die folgenden APIs für Ihr Projekt:
Console
Aktivieren Sie folgende APIs:
- Vertex AI API
- Cloud Build API
- Artifact Registry API
- Cloud Run API
- Cloud Logging API
- Discovery Engine API
- Cloud Storage API
- API für Identitäts- und Zugriffsverwaltung (IAM)
REST
Sie können diese APIs über die Google Cloud Console oder mit dem folgenden gcloud CLI-Befehl aktivieren:
gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com logging.googleapis.com discoveryengine.googleapis.com storage.googleapis.com iam.googleapis.com
Berechtigungen erteilen
Gewähren Sie die Berechtigung für die Rolle „Cloud Run-Aufrufer“ (roles/run.invoker).
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam." \
--role="roles/run.invoker"
Ersetzen Sie Folgendes:
- PROJECT_ID : die Projekt-ID.
- PROJECT_NUMBER: Ihre Google Cloud -Projektnummer.
Agent bereitstellen
Das Skript deploy.sh automatisiert den Bereitstellungsprozess. Führen Sie das Script im Projektverzeichnis mit Ihrer Google Cloud ID und einem Namen für den neuen Dienst aus, um den Agent bereitzustellen. Optional können Sie auch das zu verwendende Gemini-Modell angeben.
Das Script führt die folgenden Aktionen aus:
- Erstellt ein Container-Image aus Ihrem Quellcode.
- Überträgt das Image per Push in Artifact Registry.
- Stellt das Image in Cloud Run bereit.
- Legt Umgebungsvariablen fest, einschließlich der
MODELund der öffentlichenAGENT_URLdes Dienstes selbst.
chmod +x deploy.sh
./deploy.sh PROJECT_ID a2ui-demo-agent MODEL_NAME
Ersetzen Sie Folgendes:
- PROJECT_ID: die Projekt-ID.
- MODEL_NAME: Optional. Dies ist das dritte Argument für das Script. Unterstützte Werte sind
gemini-2.5-proundgemini-2.5-flash. Wenn nichts angegeben ist, wird standardmäßiggemini-2.5-flashverwendet.
Nach Abschluss des Skripts wird die Dienst-URL des bereitgestellten KI-Agenten ausgegeben. Sie benötigen diese Dienst-URL im nächsten Schritt.
Agent bei Gemini Enterprise registrieren
Nachdem Ihr Agent bereitgestellt wurde, müssen Sie ihn bei Gemini Enterprise registrieren, damit er gefunden werden kann.
Führen Sie den folgenden curl-Befehl aus und ersetzen Sie die Platzhalter durch Ihre eigenen Werte:
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents -d '{
"name": "a2ui-demo-agent",
"displayName": "A2UI v0.9 Demo Agent",
"description": "A demo agent that showcases A2UI v0.9 UI templates.",
"a2aAgentDefinition": {
"jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"A2UI v0.9 Demo\", \"description\": \"A demo agent that showcases A2UI v0.9 UIs built from the Material component catalog and Gemini Enterprise custom components (Canvas, Iframe). Ask it what can you do? to see the available demos.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"preferredTransport\": \"JSONRPC\", \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.9\", \"description\": \"Ability to render A2UI v0.9\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://www.gstatic.com/vertexaisearch/a2ui/v0_9/gemini_enterprise_composite_catalog.json\"]}}]}, \"skills\": [{\"id\": \"a2ui_demo\", \"name\": \"A2UI v0.9 Component Demo\", \"description\": \"Demonstrates A2UI v0.9 UIs built from the Material catalog and Gemini Enterprise custom components: cards, forms & inputs, tabs, tables, progress indicators, dialogs & menus, the Canvas side panel, and the Iframe (IFrameSrcdoc / IFrameUrl) components.\"}], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'
Ersetzen Sie Folgendes:
PROJECT_NUMBER: Ihre Google Cloud -Projektnummer.LOCATION: Der multiregionale Standort Ihres Datenspeichers:global,usodereu.ENGINE_ID: Die ID der Anwendung, mit der Sie den Agenten registrieren möchten.AGENT_URL: Die Dienst-URL des bereitgestellten KI-Agenten.
Agent abmelden (optional)
Wenn Sie die Registrierung des Agents aufheben möchten, führen Sie den folgenden curl-Befehl aus:
curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents/AGENT_ID
Ersetzen Sie Folgendes:
PROJECT_NUMBER: Ihre Google Cloud -Projektnummer.LOCATION: Der multiregionale Standort Ihres Datenspeichers:global,usodereu.ENGINE_ID: Die ID der App, mit der der Agent registriert ist.AGENT_ID: Die ID des KI-Agenten, den Sie löschen möchten.
Agenten in der Gemini Enterprise-Web-App verwenden
Nachdem ein KI-Agent erstellt und registriert wurde, können Sie ihn in der Gemini Enterprise Web-App verwenden und mit ihm interagieren.
URL der Web-App abrufen
Wenn Sie den Agenten verwenden möchten, müssen Sie zuerst die Web-App-URL abrufen. Ein Gemini Enterprise-Administrator kann die Web-App-URL so abrufen und freigeben:
Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf.
Klicken Sie auf den Namen der App, für die Sie den KI-Agenten registriert haben.
Klicken Sie auf Integrations (Integrationen).
Kopieren Sie den Link zu Ihrer Webanwendung und geben Sie ihn an die Nutzer in der Organisation weiter.
Agent verwenden
So verwenden Sie den KI-Agenten und interagieren mit ihm:
- Öffnen Sie die URL der Webanwendung in einem neuen Browsertab.
- Klicken Sie im Navigationsmenü der Webanwendung auf Agenten.
- Rufen Sie den Bereich Von Ihrer Organisation auf und klicken Sie auf den von Ihnen erstellten KI-Agenten.
- Dadurch wird die Konversationsoberfläche für den KI-Agenten geöffnet. Stellen Sie Fragen und interagieren Sie mit dem KI-Agenten.
Sie können beispielsweise einen Prompt wie Show me the recent orders table verwenden, um Informationen zu aktuellen Bestellungen zu erhalten, die Teil der Beispieldaten sind. Der Agent ruft die Bestellinformationen aus material_table_orders.json ab und rendert die Liste im Chat mithilfe von benutzerdefinierten UI-Komponenten, wie im folgenden Beispiel gezeigt:
