A2UI-Agent mit Cloud Run hosten

In dieser Anleitung wird beschrieben, wie Sie einen Agent-to-Agent-Agenten (A2A), der mit dem Google 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.

Der Beispielcode für diese Anleitung hat die folgende Ordnerstruktur.

Ordnerstruktur der Anleitung

Das Projekt hat die folgende Ordnerstruktur:

Datei/Verzeichnis Beschreibung
examples/0.8/ Verzeichnis mit Beispielkonfigurationen oder ‑daten.
__init__.py Markiert das Verzeichnis als Python-Paket.
agent.py Definiert den KI‑Agenten, seine Fähigkeiten und sein Verhalten.
agent_executor.py Verwaltet den Ausführungsablauf und die Tool-Interaktionen.
contact_data.json Beispieldaten, die vom KI-Agenten verwendet werden (z. B. Testkontakte).
deploy.sh Script zum Erstellen und Bereitstellen des Agenten in Cloud Run.
main.py Der Haupteinstiegspunkt der Anwendung (FastAPI-App).
prompt_builder.py Hilfe beim Erstellen von Prompts für das Modell.
pyproject.toml Projektkonfiguration und ‑abhängigkeiten
tools.py Definiert die Tools (Funktionen), die der 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 wechseln Sie in das Beispielverzeichnis cloud_run:

    git clone https://github.com/google/A2UI.git
cd A2UI/samples/agent/adk/gemini_enterprise/cloud_run

APIs aktivieren

Aktivieren Sie die folgenden APIs für Ihr Projekt:

Console

Aktivieren Sie folgende APIs:

  • Agent Platform 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)

APIs aktivieren

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 Invoker“ (roles/run.invoker).

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
   --role="roles/run.invoker"

Ersetzen Sie Folgendes:

  • PROJECT_ID : die ID Ihres Projekts.
  • PROJECT_NUMBER: Ihre Google Cloud Projektnummer.

Agent bereitstellen

Das deploy.sh-Skript automatisiert den Bereitstellungsprozess. Um den Agent bereitzustellen, führen Sie das Skript über das Projektverzeichnis mit Ihrer Google Cloud ID und einem Namen für den neuen Dienst aus. Sie können optional auch das zu verwendende Gemini-Modell angeben.

Das Skript führt die folgenden Aktionen aus:

  1. Erstellt ein Container-Image aus Ihrem Quellcode.
  2. Überträgt das Image per Push in Artifact Registry.
  3. Stellt das Image in Cloud Run bereit.
  4. Legt Umgebungsvariablen fest, einschließlich der MODEL und der öffentlichen AGENT_URL des Dienstes selbst.
chmod +x deploy.sh
./deploy.sh YOUR_PROJECT_ID contacts-agent MODEL_NAME

Ersetzen Sie Folgendes:

  • PROJECT_ID: die Projekt-ID.
  • MODEL_NAME: Optional. Dies ist das dritte Argument für das Skript. Unterstützte Werte sind gemini-2.5-pro und gemini-2.5-flash. Wenn nichts angegeben ist, wird standardmäßig gemini-2.5-flash verwendet.

Sobald das Skript abgeschlossen ist, wird die Dienst-URL Ihres bereitgestellten Agents 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": "contacts-agent",
"displayName": "Contacts Agent",
"description": "This is a test agent which lists the contacts.",
"a2aAgentDefinition": {
  "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"contacts-agent\", \"description\": \"This is a test agent which lists the contacts.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.8\", \"description\": \"Ability to render A2UI\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://a2ui.org/specification/v0_8/standard_catalog_definition.json\"]}}]}, \"skills\": [], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'

Ersetzen Sie Folgendes:

  • PROJECT_NUMBER: Ihre Google Cloud Projektnummer.
  • LOCATION: Der multiregionale Standort Ihres Datenspeichers: global, us oder eu.
  • ENGINE_ID: Die ID der App, mit der Sie den Agenten registrieren möchten.
  • AGENT_URL: Die Dienst-URL Ihres bereitgestellten Agenten.

Agent in der Gemini Enterprise-Web-App verwenden

Nachdem Sie einen KI-Agenten erstellt und registriert haben, können Sie ihn in der Gemini Enterprise Web-App verwenden und mit ihm interagieren.

URL der Web-App abrufen

Wenn Sie den Agent 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:

  1. Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf.

    Gemini Enterprise

  2. Klicken Sie auf den Namen der App, für die Sie den Agenten registriert haben.

  3. Klicken Sie auf Integrations (Integrationen).

  4. 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:

  1. Öffnen Sie die URL der Webanwendung in einem neuen Browsertab.
  2. Klicken Sie im Navigationsmenü der Webanwendung auf Agenten.
  3. Rufen Sie den Bereich Von Ihrer Organisation auf und klicken Sie auf den von Ihnen erstellten Agenten.
  4. 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 den Agenten beispielsweise bitten, alle Kontakte aufzulisten. Der Agent verwendet das Tool list_contacts, um die Kontakte aus contact_data.json abzurufen, und rendert die Liste im Chat mithilfe benutzerdefinierter UI-Elemente, wie im folgenden Beispiel gezeigt:

Beispiel für einen Kontakte-Agent