Google Chat-App mit einem Agent2UI-Agenten erstellen

Diese Seite erklärt, wie man ein Google Workspace-Add-on erstellt, das in Google Chat funktioniert und mit einem KI-Agenten interagiert, der das Agent2UI (A2UI)-Protokoll verwendet. Sie entwickeln den Agenten mithilfe des Agent Development Kit (ADK) und hosten ihn in der Vertex AI Agent Engine.

KI-Agenten nehmen ihre Umgebung autonom wahr, argumentieren und führen komplexe, mehrstufige Aktionen aus, um ein definiertes Ziel zu erreichen. In diesem Tutorial stellen Sie einen einfachen KI-Agenten bereit, der statische Profilinformationen zurückgibt, die von einem Tool abgerufen werden.

A2UI ermöglicht es KI-Agenten, adaptive, reichhaltige und interaktive Benutzeroberflächen zu generieren, die nativ gerendert werden. Sie können sich dann auf die Logik der KI-Agenten konzentrieren, nicht auf die Benutzeroberflächen.

Abbildung 1. Der A2UI-Agent antwortet dem Benutzer mit Text und einer Karte, die den Namen, ein Bild und eine LinkedIn-Schaltfläche enthält.
Abbildung 2: Der A2UI-Agent wurde aktualisiert, sodass er auch den Profiltitel zurückgibt.
Abbildung 3: Der A2UI-Agent antwortet dem Nutzer mit einer Nachricht, in der der Profilname auf der Karte angezeigt wird.

Das folgende Diagramm zeigt die Architektur und das Messaging-Muster:

Architektur einer Chat-App, die mit einem A2UI-KI-Agenten implementiert wurde.

Im Diagramm wird der Informationsfluss bei der Interaktion eines Nutzers mit einer Chat-App dargestellt, die mit einem A2UI-Agenten implementiert wurde:

Ein Nutzer sendet eine Nachricht an eine Chat-App, entweder als Direktnachricht oder in einem Chat-Bereich.
Die in Apps Script oder als Webserver mit HTTP-Endpunkten implementierte Chat-App-Logik empfängt und verarbeitet die Nachricht.
Der in Vertex AI Agent Engine gehostete A2UI-Agent empfängt und verarbeitet die Interaktion.
Optional kann die Chat-App oder der KI-Agent in Google Workspace-Dienste wie Google Kalender oder Google Tabellen oder in andere Google-Dienste wie Google Maps oder YouTube eingebunden werden.
Die Chat-App generiert und sendet adaptive Antworten asynchron. Dabei wird die Google Chat API verwendet, um den Fortschritt des KI-Agenten zu kommunizieren.
Die Antworten werden an den Nutzer gesendet.

Ziele

die Umgebung einrichten
A2UI-Agent bereitstellen
Stellen Sie die Chat App bereit.
Konfigurieren Sie die Chat App.
Chat App testen

Vorbereitung

Ein Google Workspace-Konto für Unternehmen mit Zugriff auf Google Chat.
Google Cloud-Projekt mit aktivierter Abrechnungsfunktion. Informationen dazu, wie Sie prüfen können, ob die Abrechnung für ein bestehendes Projekt aktiviert ist, finden Sie unter Abrechnungsstatus Ihrer Projekte prüfen. Informationen zum Erstellen eines Projekts und Einrichten der Abrechnung finden Sie unter Google Cloud-Projekt erstellen.
Python 3.11 oder höher: Folgen Sie zur Installation der Anleitung auf der offiziellen Python-Website.
Python Poetry: Folgen Sie zur Installation der Anleitung auf der offiziellen Poetry-Website.
Google Cloud CLI: Folgen Sie zur Installation der Anleitung auf der offiziellen Google Cloud-Website.

Umgebung einrichten

Google Cloud APIs aktivieren

Bevor Sie Google APIs verwenden können, müssen Sie sie in einem Google Cloud-Projekt aktivieren. Sie können eine oder mehrere APIs in einem einzelnen Google Cloud-Projekt aktivieren.

Aktivieren Sie in der Google Cloud Console die Google Chat API, die Vertex AI API und die Cloud Resource Manager API.

APIs aktivieren

OAuth-Zustimmungsbildschirm konfigurieren

Für alle Apps, die OAuth 2.0 verwenden, ist eine Konfiguration des Zustimmungsbildschirms erforderlich. Wenn Sie den OAuth-Zustimmungsbildschirm Ihrer App konfigurieren, legen Sie fest, was Nutzern und App-Prüfern angezeigt wird. Außerdem wird Ihre App registriert, damit Sie sie später veröffentlichen können.

Rufen Sie in der Google Cloud Console das Menü > Google Auth platform > Branding auf.
Zum Branding
Wenn Sie die Google Auth platformbereits konfiguriert haben, können Sie die folgenden Einstellungen für den OAuth-Zustimmungsbildschirm unter Branding, Zielgruppe und Datenzugriff konfigurieren. Wenn Sie die Meldung Google Auth platform noch nicht konfiguriert sehen, klicken Sie auf Jetzt starten:

Geben Sie unter App-Informationen im Feld App-Name einen Namen für die App ein.
Wählen Sie unter E-Mail-Adresse des Nutzersupports eine Support-E-Mail-Adresse aus, über die Nutzer Sie mit Fragen zu ihrer Einwilligung kontaktieren können.
Klicken Sie auf Weiter.
Wählen Sie unter Zielgruppe die Option Intern aus.
Klicken Sie auf Weiter.
Geben Sie unter Kontaktdaten eine E-Mail-Adresse ein, unter der Sie über Änderungen an Ihrem Projekt benachrichtigt werden können.
Klicken Sie auf Weiter.
Sehen Sie sich unter Abschließen die Nutzerdatenrichtlinie für Google API-Dienste an. Wenn Sie damit einverstanden sind, wählen Sie Ich stimme der Nutzerdatenrichtlinie für Google API-Dienste zu aus.
Klicken Sie auf Weiter.
Klicken Sie auf Erstellen.

Sie können das Hinzufügen von Scopes vorerst überspringen. Wenn Sie in Zukunft eine App erstellen, die außerhalb Ihrer Google Workspace-Organisation verwendet werden soll, müssen Sie den Benutzertyp User type in Extern ändern. Fügen Sie anschließend die Autorisierungsbereiche hinzu, die Ihre App benötigt. Weitere Informationen finden Sie im vollständigen Leitfaden Configure OAuth consent.

Erstellen Sie ein Dienstkonto in der Google Cloud Console.

Erstellen Sie ein neues Dienstkonto mit der Rolle Vertex AI User, indem Sie die folgenden Schritte ausführen:

Google Cloud Console

In der Google Cloud Console gehen Sie zu Menü > IAM & Admin > Dienstkonten.
Zur Seite „Dienstkonten“
Klicken Sie auf Dienstkonto erstellen.
Geben Sie die Details des Servicekontos ein und klicken Sie dann auf Erstellen und fortfahren.
Hinweis: Standardmäßig erstellt Google eine eindeutige Dienstkonto-ID. Wenn Sie die ID ändern möchten, modifizieren Sie die ID im Feld „Dienstkonto-ID“.
Optional: Weisen Sie Ihrem Dienstkonto Rollen zu, um Zugriff auf die Ressourcen Ihres Google Cloud-Projekts zu gewähren. Weitere Informationen finden Sie unter Zugriff auf Ressourcen erteilen, ändern und entziehen.
Klicken Sie auf Weiter.
Optional: Geben Sie Nutzer oder Gruppen ein, die dieses Dienstkonto verwalten und Aktionen damit ausführen können. Weitere Informationen finden Sie unter Identitätswechsel von Dienstkonten verwalten.
Klicken Sie auf Fertig. Notieren Sie sich die E-Mail-Adresse des Dienstkontos.

gcloud-CLI

Erstellen Sie das Dienstkonto:

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"

Optional: Weisen Sie Ihrem Dienstkonto Rollen zu, um Zugriff auf die Ressourcen Ihres Google Cloud-Projekts zu gewähren. Weitere Informationen finden Sie unter Zugriff auf Ressourcen erteilen, ändern und entziehen.

Das Dienstkonto wird auf der Seite mit den Dienstkonten angezeigt.

Privaten Schlüssel erstellen

So erstellen und laden Sie einen privaten Schlüssel für das Dienstkonto herunter:

Rufen Sie in der Google Cloud Console das Menü > IAM & Verwaltung > Dienstkonten auf.
Zur Seite „Dienstkonten“
Wählen Sie Ihr Dienstkonto aus.
Klicken Sie auf Keys > Schlüssel hinzufügen > Neuen Schlüssel erstellen.
Wählen Sie JSON aus und klicken Sie dann auf Erstellen.
Ihr neues öffentliches/privates Schlüsselpaar wird generiert und als neue Datei auf Ihren Rechner heruntergeladen. Speichern Sie die heruntergeladene JSON-Datei unter dem Namen credentials.json in Ihrem Arbeitsverzeichnis. Diese Datei ist die einzige Kopie dieses Schlüssels. Informationen zur sicheren Aufbewahrung Ihres Schlüssels finden Sie unter Verwaltung von Dienstkontoschlüsseln.
Klicken Sie auf Schließen.

Weitere Informationen zu Dienstkonten finden Sie unter Dienstkonten in der Google Cloud IAM-Dokumentation.

Stellen Sie den A2UI-Agenten bereit.

Falls Sie dies noch nicht getan haben, authentifizieren Sie sich mit Ihrem Google Cloud-Konto und konfigurieren Sie die Google Cloud CLI so, dass sie Ihr Google Cloud-Projekt verwendet.
```
gcloud auth application-default login
gcloud config set project PROJECT_ID
gcloud auth application-default set-quota-project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch die ID Ihres Cloud-Projekts.
Laden Sie das googleworkspace/add-ons-samples GitHub-Repository mit dieser Schaltfläche herunter:

Repository herunterladen
Entpacken Sie in Ihrer bevorzugten lokalen Entwicklungsumgebung die heruntergeladene Archivdatei und öffnen Sie das Verzeichnis add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui.
```
unzip add-ons-samples-main.zip
cd add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui
```
Erstellen Sie einen neuen Cloud Storage-Bucket, der dem ADK-Agenten gewidmet ist.
```
gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION
```
Ersetzen Sie Folgendes:
1. CLOUD_STORAGE_BUCKET_NAME mit einem eindeutigen Bucket-Namen, den Sie verwenden möchten.
2. PROJECT_ID durch die ID Ihres Cloud-Projekts.
3. PROJECT_LOCATION mit dem Speicherort Ihres Cloud-Projekts.
Legen Sie die folgenden Umgebungsvariablen fest:
```
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
```
Ersetzen Sie Folgendes:
1. CLOUD_STORAGE_BUCKET_NAME mit dem Namen des von Ihnen erstellten Buckets.
2. PROJECT_ID durch die ID Ihres Cloud-Projekts.
3. PROJECT_LOCATION mit dem Standort Ihres Cloud-Projekts.

Installieren und bereitstellen Sie den ADK-Agenten aus einer virtuellen Umgebung.

python3 -m venv myenv
source myenv/bin/activate
poetry install --with deployment
python3 deployment/deploy.py --create

Rufen Sie die Agent-ID ab. Sie benötigen sie später, wenn Sie die Chat-App konfigurieren.
```
python3 deployment/deploy.py --list
```

Chat-App-Projekt erstellen und konfigurieren

Klicken Sie auf die folgende Schaltfläche, um das Apps Script-Projekt A2UI AI Agent Quickstart zu öffnen.

Projekt öffnen
Klicken Sie auf Übersicht > Kopie erstellen.
Klicken Sie in Ihrem Apps Script-Projekt auf Projekteinstellungen > Skripteigenschaften bearbeiten > Skripteigenschaft hinzufügen, um die folgenden Skripteigenschaften hinzuzufügen:
1. REASONING_ENGINE_RESOURCE_NAME durch den Namen der Vertex AI-Agent-Ressource, die Sie in den vorherigen Schritten kopiert haben.
2. Ersetzen Sie SERVICE_ACCOUNT_KEY durch den JSON-Schlüssel des Dienstkontos, der in den vorherigen Schritten heruntergeladen wurde, z. B. { ... }.
Klicken Sie auf Skripteigenschaften speichern.
Rufen Sie in der Google Cloud Console das Menü > IAM und Verwaltung > Einstellungen auf.

Weiter zur Seite „IAM & Verwaltung“
Kopieren Sie den Wert aus dem Feld Projektnummer.
Klicken Sie in Ihrem Apps Script-Projekt auf Projekteinstellungen.
Klicken Sie unter Google Cloud Platform-Projekt (GCP) auf Projekt wechseln.
Fügen Sie unter GCP-Projektnummer die Google Cloud-Projektnummer ein, die Sie in den vorherigen Schritten kopiert haben.
Klicken Sie auf Projekt festlegen. Das Cloud-Projekt und das Apps Script-Projekt sind jetzt verbunden.

Testbereitstellung erstellen

Sie benötigen eine Bereitstellungs-ID für dieses Apps Script-Projekt, damit Sie es im nächsten Schritt verwenden können.

So rufen Sie die ID des Head-Deployments ab:

Klicken Sie im Apps Script-Projekt der Chat-App auf Bereitstellen > Bereitstellungen testen.
Klicken Sie unter Head-Deployment-ID auf Kopieren.
Klicken Sie auf Fertig.

Chat App konfigurieren

Gehen Sie so vor, um die Google Chat-App mithilfe Ihres Apps Script-Deployments zum Testen bereitzustellen:

Suchen Sie in der Konsole nach Google Chat API und klicken Sie auf Google Chat API.
Klicken Sie auf Verwalten.
Klicken Sie auf Konfiguration und richten Sie die Chat-App ein:
1. Geben Sie im Feld App-Name den Namen A2UI Quickstart ein.
2. Geben Sie im Feld Avatar-URL https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png ein.
3. Geben Sie im Feld Beschreibung den Text A2UI Quickstart ein.
4. Wählen Sie unter Funktionsweise die Option Gruppenbereichen und Gruppenunterhaltungen beitreten aus.
5. Wählen Sie unter „Verbindungseinstellungen“ die Option Apps Script-Projekt aus.
6. Fügen Sie in das Feld Deployment ID (Deployment-ID) die Head-Deployment-ID ein, die Sie zuvor kopiert haben.
7. Wählen Sie unter „Sichtbarkeit“ die Option Bestimmte Personen und Gruppen in Ihrer Domain aus und geben Sie Ihre E‑Mail-Adresse ein.
Klicken Sie auf Speichern.

Die Chat App ist bereit, auf Nachrichten zu antworten.

Chat App testen

So testen Sie Ihre Chat-App: Öffnen Sie einen Direktnachrichtenbereich mit der Chat-App und senden Sie eine Nachricht:

Öffnen Sie Google Chat mit dem Google Workspace-Konto, das Sie angegeben haben, als Sie sich als vertrauenswürdiger Tester hinzugefügt haben.

Zu Google Chat wechseln
Klicken Sie auf Neuer Chat.
Geben Sie im Feld Eine oder mehrere Personen hinzufügen den Namen Ihrer Chat-App ein.
Wählen Sie Ihre Chat-App aus den Ergebnissen aus. Eine Direktnachricht wird geöffnet.

Notiz: Wenn Ihre Chat-App nicht in der Ergebnisliste angezeigt wird, stellen Sie sicher, dass Sie Ihr Google Workspace-Konto hinzugefügt haben. Sichtweite Einstellungen der Chat-API-Konfiguration Seite in der Google Cloud Console.
In der neuen Direktnachricht mit der App Hello! eingeben und enter drücken.

Die Chat-App antwortet mit einer Begrüßungsnachricht und einer Karte, die den Profilnamen, das Profilbild und die LinkedIn-Schaltfläche enthält.

Aktualisieren Sie die Implementierung des A2UI-Agenten, sodass nun auch der Profiltitel zurückgegeben wird.

Öffnen Sie in Ihrer lokalen Entwicklungsumgebung die Datei a2ui/agent.py und entfernen Sie die Kommentarzeichen in der Zeile des Tools, das den Titel zu den zurückgegebenen Daten hinzufügt.

apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py

Auf GitHub ansehen

# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""A2UI agent."""

from google.adk.agents import LlmAgent
from google.adk.tools.tool_context import ToolContext
import json

# The schema for any A2UI message. This never changes.
from .a2ui_schema import A2UI_SCHEMA

def get_user_profile(tool_context: ToolContext) -> str:
    """Call this tool to get the current user profile."""
    return json.dumps({
        "name": "Pierrick Voulet",
        # "title": "DevRel Engineer @ Google Workspace | Gen AI & AI Agents & Agentic AI | Automation & Digital Transformation",
        "imageUrl": "https://io.google/2024/speakers/3ea87822-3160-4d54-89dd-57e185085f79_240.webp",
        "linkedin": "https://www.linkedin.com/in/pierrick-voulet/"
    })

AGENT_INSTRUCTION="""
You are a user profile assistant. Your goal is to help users get their profile information using a rich UI.

To achieve this, you MUST follow these steps to answer user requests:

1.  You MUST call the `get_user_profile` tool and extract all the user profile information from the result.
2.  You MUST generate a final a2ui UI JSON based on the user profile information extracted in the previous step."""

A2UI_AND_AGENT_INSTRUCTION = AGENT_INSTRUCTION + f"""

To generate a valid a2ui UI JSON, you MUST follow these rules:
1.  Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`.
2.  The first part is your conversational text response.
3.  The second part is a single, raw JSON object which is a list of A2UI messages.
4.  The JSON part MUST validate against the A2UI JSON SCHEMA provided below.

To represent the user profile, you MUST use the following A2UI message types:
1.  Buttons MUST be used to represent links (e.g., LinkedIn profile link).
2.  Image MUST be used to represent the user's profile picture.

---BEGIN A2UI JSON SCHEMA---
{A2UI_SCHEMA}
---END A2UI JSON SCHEMA---
"""

root_agent = LlmAgent(
    name="user_profile",
    model="gemini-2.5-flash",
    instruction=A2UI_AND_AGENT_INSTRUCTION,
    description="An agent that returns the current user profile.",
    tools=[get_user_profile]
)

Aktualisieren Sie das zuvor bereitgestellte ADK mit der neuen Version der Implementierung.
```
python3 deployment/deploy.py --update --resource_id=RESOURCE_ID
```
Ersetzen Sie RESOURCE_ID durch den in den vorherigen Schritten kopierten Ressourcennamen des Vertex AI-Agenten.
Gib in der Direktnachricht mit der App Hello again! ein und drücke enter.

Die Chat-App antwortet mit einer Nachricht, die etwas Text und eine Karte mit dem Profiltitel enthält.

Um vertrauenswürdige Tester hinzuzufügen und mehr über das Testen interaktiver Funktionen zu erfahren, siehe Testen interaktiver Funktionen für Google Chat-Apps.

Fehlerbehebung

Wenn eine Google Chat-App oder card einen Fehler zurückgibt, wird auf der Chat-Oberfläche eine Meldung angezeigt, die besagt: „Etwas ist schiefgelaufen.“ oder "Ihre Anfrage konnte nicht bearbeitet werden." Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, aber die Chat-App oder -Karte liefert ein unerwartetes Ergebnis; zum Beispiel wird eine Kartennachricht möglicherweise nicht angezeigt.

Auch wenn in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt wird, stehen Ihnen beschreibende Fehlermeldungen und Protokolldaten zur Verfügung, die Ihnen bei der Fehlerbehebung helfen, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Hilfe zum Anzeigen, Debuggen und Beheben von Fehlern finden Sie unter Fehlerbehebung und -behebung bei Google Chat.

Bereinigen

Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, empfehlen wir, das Cloud-Projekt zu löschen.

Achtung:Das Löschen eines Projekts hat folgende Auswirkungen:

Alle Inhalte des Projekts werden gelöscht. Wenn Sie für diese Anleitung ein bereits bestehendes Projekt verwendet haben, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID verwenden, z. B. eine URL auf appspot.com, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, statt das gesamte Projekt.

Wenn Sie mehrere Anleitungen und Kurzanleitungen durcharbeiten möchten, können Sie die Überschreitung von Projektkontingenten verhindern, indem Sie Projekte wiederverwenden.

Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten. Klicken Sie auf das Menü > IAM & Verwaltung > Ressourcen verwalten.
Zum Ressourcenmanager
Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie dann auf Löschen .
Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Beenden, um das Projekt zu löschen.