Reisen mit einem KI‑Agenten planen, auf den in Google Workspace zugegriffen werden kann

Programmierkenntnisse: Fortgeschritten 
Dauer: 45 Minuten 
Projekttyp: Google Workspace-Add-on für Chat, Gmail, Kalender, Drive, Docs, Sheets und Präsentationen.

In dieser Anleitung wird beschrieben, wie Sie KI-Agents als Google Workspace-Add-ons in Google Workspace veröffentlichen. Dazu können Sie Apps Script oder HTTP-Endpunkte verwenden. Nachdem Sie Ihr Add-on veröffentlicht haben, können Ihre Nutzer mit den KI-Agents in ihren Arbeitsabläufen interagieren.

Übersicht

In dieser Anleitung stellen Sie das Travel Concierge-Beispiel aus dem Agent Development Kit (ADK) bereit. Der Reise-Concierge ist eine konversationelle Multi-Agent-KI, die Tools wie die Google Maps Platform Places API, Google Search Grounding und einen MCP-Server (Model Context Protocol) verwendet.

Das ADK bietet standardmäßig Chat- und Textschnittstellen für Entwickler. In diesem Tutorial fügen Sie Google Workspace-Anwendungen eine grafische Benutzeroberfläche (GUI) hinzu, auf die Ihre Nutzer direkt in Chat, Gmail, Google Kalender, Drive, Docs, Sheets und Präsentationen zugreifen können.

• 

  Abbildung 1. Mit dem KI‑Agenten von Chat Reiseideen sammeln.

• 

  Abbildung 2. Mit dem KI‑Agenten in Gmail eine Reise auf Grundlage des Kontexts der ausgewählten E‑Mail planen

Ziele

• Umgebung einrichten
• Stellen Sie den KI-Agenten bereit.
• Richten Sie das Projekt ein.
• Bereitstellung für Gmail, Google Kalender, Google Drive, Google Docs, Google Sheets und Google Präsentationen.
• In Chat bereitstellen
• Lösung testen

Informationen zu dieser Lösung

Diese Lösung basiert auf den folgenden Kerntechnologien: dem ADK, Google Cloud und den Google Workspace-APIs, der Vertex AI Agent Engine und dem Karten-Framework.

Die Benutzeroberflächen sind für Chat- und Nicht-Chat-Anwendungen (Gmail, Kalender, Drive, Docs, Sheets, Präsentationen) unterschiedlich gestaltet, um den jeweiligen Funktionen und Einschränkungen Rechnung zu tragen.

Funktionen

Die folgenden Funktionen der Travel Concierge-Anwendung sind für alle Google Workspace-Anwendungen gleich:

• Persistente Nutzersitzungen:Sitzungen werden von Vertex AI verwaltet, um die Persistenz zu gewährleisten. Jeder Nutzer teilt sich eine Sitzung für alle Workspace-Anwendungen. Nutzer können ihre Sitzung manuell zurücksetzen, um eine neue Unterhaltung zu starten.

• Rich Messaging:Nutzer senden SMS und erhalten Antworten mit Rich-Text und Karten-Widgets.

• Fehlerbehandlung: Unerwartete Fehler werden mithilfe konfigurierbarer Wiederholungsversuche und Statusmeldungen in den Antworten auf elegante Weise behandelt.

Die Chat App bietet die folgenden zusätzlichen Funktionen:

• Multimodale Benutzer-Messaging: Benutzer können Nachrichten mit Anhängen senden, einschließlich Audio- und Videoaufnahmen, die direkt im Chatbereich aufgezeichnet wurden.

• Visuell ansprechendere Antworten:Antworten können mit anspruchsvolleren Widgets wie Karussells mit Bildern generiert werden, indem nur Chatfunktionen des Card-Frameworks und mehr Rendering-Platz genutzt werden.

Andere Anwendungen bieten die folgenden zusätzlichen Funktionen:

• Google-Profilkontext:Nutzer können Nachrichten mit ihren Profilinformationen senden (in diesem Beispiel auf Geburtstage beschränkt).

• Gmail-Kontext:Nutzer können Nachrichten mit E-Mails senden (in diesem Beispiel auf ein Betreff und einen Text beschränkt).

• Zugriff des Kundenservicemitarbeiters auf Chatbereiche:Nutzer können den Direktnachrichtenbereich der Chat-App mit einem Klick auf eine Schaltfläche in einem neuen Tab öffnen.

Architektur

Die Travel Concierge-Anwendung empfängt und verarbeitet Google Workspace-Add-on-Interaktionsereignisse von Google Workspace-Anwendungen, verwendet Vertex AI, um den ADK-KI-Agent zu steuern und Nutzersitzungen zu verwalten, und nutzt Google Cloud- und Google Workspace-APIs, um Kontext zu erfassen und Antworten anzuzeigen.

Das folgende Diagramm zeigt den Haupt-User Flow: eine Nachricht an den KI-Agenten senden.

HTTP

• 

  Abbildung 3. Die Chat-App vervollständigt den Kontext mit Anhängen aus der Benutzernachricht und sendet eine Reihe von Nachrichten mit dem Verlauf der Interaktionen der Unteragenten und der endgültigen Gesamtantwort in chronologischer Reihenfolge.

• 

  Abbildung 4. Die Nicht-Chat-Anwendungen ergänzen den Kontext mit dem Google-Profil des Nutzers und der Artikelauswahl und zeigen eine Reihe von Abschnitten mit dem Verlauf der Sub-Agent-Interaktionen und der endgültigen Gesamtantwort in umgekehrt chronologischer Reihenfolge an.

Apps Script

• 

  Abbildung 3. Die Chat-App vervollständigt den Kontext mit Anhängen aus der Nutzernachricht und sendet eine Reihe von Nachrichten mit dem Verlauf der Sub-Agent-Interaktionen und der endgültigen Gesamtantwort in chronologischer Reihenfolge.

• 

  Abbildung 4. Die Nicht-Chat-Anwendungen ergänzen den Kontext mit dem Google-Profil des Nutzers und der Artikelauswahl und zeigen eine Reihe von Abschnitten mit dem Verlauf der Sub-Agent-Interaktionen und der endgültigen Gesamtantwort in umgekehrt chronologischer Reihenfolge an.

Vorbereitung

• Ein Google Workspace-Konto für Unternehmen mit Zugriff auf Google Chat.

• Ein Webbrowser mit Internetzugriff.

• Spezifische Voraussetzungen für den ADK-KI-Agenten „Travel Concierge“

  • Python 3.10 oder höher: Folgen Sie zur Installation der Anleitung auf der offiziellen Python-Website.
  • uv: Folgen Sie für die Installation der Anleitung auf der offiziellen uv-Website.
  • Google Cloud CLI: Folgen Sie zur Installation der Anleitung auf der offiziellen Google Cloud-Website.

Umgebung vorbereiten

In diesem Abschnitt wird beschrieben, wie Sie ein Google Cloud-Projekt erstellen und konfigurieren.

Google Cloud-Projekt erstellen

Google Cloud Console

1. Rufen Sie in der Google Cloud Console das Menü  > IAM und Verwaltung > Projekt erstellen auf.

   Zur Seite „Projekt erstellen“

2. Geben Sie im Feld Projektname einen aussagekräftigen Namen für Ihr Projekt ein.

   Optional: Wenn Sie die Projekt-ID bearbeiten möchten, klicken Sie auf Bearbeiten. Die Projekt-ID kann nach dem Erstellen des Projekts nicht mehr geändert werden. Wählen Sie also eine ID aus, die während der gesamten Dauer des Projekts den Anforderungen entspricht.

3. Klicken Sie im Feld Speicherort auf Durchsuchen, um mögliche Speicherorte für Ihr Projekt aufzurufen. Klicken Sie danach auf Auswählen.
   Achtung: Sie können Ihre Google Workspace-Organisation nicht finden?
   Das bedeutet, dass Sie nicht in einem Google Workspace-Konto angemeldet sind. Einige der Funktionen, die in der Google Workspace-Entwicklerdokumentation beschrieben werden, sind nur für Projekte verfügbar, die mit einer Organisation verknüpft sind.
4. Klicken Sie auf Erstellen. In der Google Cloud Console wird die Seite „Dashboard“ aufgerufen und Ihr Projekt wird innerhalb weniger Minuten erstellt.

gcloud-CLI

Greifen Sie in einer der folgenden Entwicklungsumgebungen auf die Google Cloud CLI (gcloud) zu:

• Cloud Shell: Aktivieren Sie Cloud Shell, um ein Onlineterminal mit der bereits eingerichteten gcloud CLI zu verwenden.
  Cloud Shell aktivieren
• Lokale Shell: Zur Verwendung einer lokalen Entwicklungsumgebung müssen Sie die gcloud CLI installieren und initialisieren.
  Verwenden Sie zum Erstellen eines Cloud-Projekts den Befehl gcloud projects create:

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch die ID des Projekts, das Sie erstellen möchten.

Abrechnung für das Cloud-Projekt aktivieren

Wenn Sie kein Rechnungskonto verknüpfen können, haben Sie nicht die erforderlichen Berechtigungen, um diese Änderung vorzunehmen. Weitere Informationen finden Sie unter Erforderliche Berechtigungen zum Aktivieren der Abrechnung.

Google Cloud Console

1. Rufen Sie in der Google Cloud Console die Seite Abrechnung auf. Klicken Sie auf das Menü > Abrechnung > Meine Projekte.

   Zur Abrechnung für meine Projekte

2. Wählen Sie unter Organisation auswählen die Organisation aus, die mit Ihrem Google Cloud-Projekt verknüpft ist.
3. Öffnen Sie in der Projektzeile das Menü Aktionen (), klicken Sie auf Abrechnung ändern und wählen Sie das Cloud Billing-Konto aus.
4. Klicken Sie auf Konto festlegen.

gcloud-CLI

1. Führen Sie folgenden Befehl aus, um verfügbare Rechnungskonten aufzulisten:

   gcloud billing accounts list

2. Rechnungskonto mit einem Google Cloud-Projekt verknüpfen:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Ersetzen Sie Folgendes:

   • PROJECT_ID ist die Projekt-ID für das Cloud-Projekt, für das Sie die Abrechnung aktivieren möchten.
   • BILLING_ACCOUNT_ID ist die Rechnungskonto-ID, die mit dem Google Cloud-Projekt verknüpft werden soll.

Google Cloud APIs aktivieren

HTTP

1. Aktivieren Sie in der Google Cloud Console die APIs für Vertex AI, Places, People, Google Chat, Gmail, Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry, Cloud Run und Google Workspace-Add-ons.

   APIs aktivieren

2. Bestätigen Sie, dass Sie die APIs im richtigen Cloud-Projekt aktivieren, und klicken Sie auf Weiter.

3. Prüfen Sie, ob Sie die richtigen APIs aktivieren, und klicken Sie dann auf Aktivieren.

Apps Script

1. Aktivieren Sie in der Google Cloud Console die Vertex AI-, Places-, People- und Google Chat-APIs.

   APIs aktivieren

2. Bestätigen Sie, dass Sie die APIs im richtigen Cloud-Projekt aktivieren, und klicken Sie auf Weiter.

3. Prüfen Sie, ob Sie die richtigen APIs aktivieren, und klicken Sie dann auf Aktivieren.

API-Schlüssel für die Google Maps Platform Places API abrufen

1. Rufen Sie in der Google Cloud Console die Seite Google Maps Platform > Schlüssel & Anmeldedaten auf.

   Zu „Schlüssel und Anmeldedaten“

2. Im Dialogfeld Erste Schritte auf der Google Maps Platform wird der neu erstellte API-Schlüssel angezeigt, ein alphanumerischer String. Sie benötigen diese Zeichenkette in den nächsten Abschnitten.

Hinweis :Wenn Sie bereits einen geeigneten API-Schlüssel haben, wird die Liste der API-Schlüssel und nicht das Dialogfeld Erste Schritte mit der Google Maps Platform angezeigt. Wählen Sie Schlüssel anzeigen aus, um den Schlüssel einzublenden.

Dienstkonto in der Google Cloud Console erstellen

Erstellen Sie ein neues Dienstkonto mit der Rolle Vertex AI User. Gehen Sie dazu so vor:

Google Cloud Console

1. Rufen Sie in der Google Cloud Console das Menü  > IAM & Verwaltung > Dienstkonten auf.

   Zur Seite „Dienstkonten“

2. Klicken Sie auf Dienstkonto erstellen.
3. 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“.
4. 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.
5. Klicken Sie auf Weiter.
6. 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.
7. Klicken Sie auf Fertig. Notieren Sie sich die E-Mail-Adresse des Servicekontos.

gcloud-CLI

1. Erstellen Sie das Dienstkonto:

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

2. 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. Erstellen Sie als Nächstes einen privaten Schlüssel für das Dienstkonto.

Privaten Schlüssel erstellen

Warnung : In diesem Beispiel wird der Einfachheit halber ein exportierter Dienstkontoschlüssel verwendet. Das Exportieren eines privaten Schlüssels wird in der Produktion nicht empfohlen, da er nicht an einem unsicheren Ort wie der Quellcodeverwaltung gespeichert werden sollte.

Weitere Informationen zu sicheren Dienstkontoimplementierungen und Best Practices finden Sie unter Auswahl des richtigen Zeitpunkts für die Verwendung von Dienstkonten.

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

1. Rufen Sie in der Google Cloud Console das Menü  > IAM & Verwaltung > Dienstkonten auf.

   Zur Seite „Dienstkonten“

2. Wählen Sie Ihr Dienstkonto aus.
3. Klicken Sie auf Schlüssel > Schlüssel hinzufügen > Neuen Schlüssel erstellen.
4. Wählen Sie JSON aus und klicken Sie auf Erstellen.

   Ihr neues öffentliches/privates Schlüsselpaar wird generiert und als neue Datei auf Ihren Computer heruntergeladen. Speichern Sie die heruntergeladene JSON-Datei als credentials.json in Ihrem Arbeitsverzeichnis. Diese Datei ist die einzige Kopie dieses Schlüssels. Informationen dazu, wie Sie den Schlüssel sicher speichern, finden Sie unter Dienstkontoschlüssel verwalten.

5. Klicken Sie auf Schließen.

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

OAuth-Zustimmungsbildschirm konfigurieren

Für Google Workspace-Add-ons ist eine Konfiguration des Zustimmungsbildschirms erforderlich. Wenn Sie den OAuth-Zustimmungsbildschirm Ihres Add-ons konfigurieren, legen Sie fest, was Google den Nutzern anzeigt.

1. Rufen Sie in der Google Cloud Console das Menü  > Google Auth platform > Branding auf.

   Zum Branding

2. 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:
1. Geben Sie unter App-Informationen im Feld App-Name einen Namen für die App ein.
2. 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.
3. Klicken Sie auf Weiter.
4. Wählen Sie unter Zielgruppe die Option Intern aus.
5. Klicken Sie auf Weiter.
6. Geben Sie unter Kontaktdaten eine E-Mail-Adresse ein, unter der Sie über Änderungen an Ihrem Projekt benachrichtigt werden können.
7. Klicken Sie auf Weiter.
8. 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.
9. Klicken Sie auf Weiter.
10. Klicken Sie auf Erstellen.
3. Sie können das Hinzufügen von Bereichen vorerst überspringen. Wenn Sie in Zukunft eine App für die Verwendung außerhalb Ihrer Google Workspace-Organisation erstellen, müssen Sie den Nutzertyp in Extern ändern. Fügen Sie dann die Autorisierungsbereiche hinzu, die für Ihre App erforderlich sind. Weitere Informationen finden Sie in der vollständigen Anleitung OAuth-Zustimmung konfigurieren.

KI-Agent für Reise-Concierge-ADK bereitstellen

1. Falls noch nicht geschehen, authentifizieren Sie sich mit Ihrem Google Cloud-Konto und konfigurieren Sie die Google Cloud CLI für die Verwendung Ihres Google Cloud-Projekts.

   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 des Cloud-Projekts, das Sie erstellt haben.

2. Dieses GitHub-Repository herunterladen

   Herunterladen

3. Extrahieren Sie in Ihrer bevorzugten lokalen Entwicklungsumgebung die heruntergeladene Archivdatei und öffnen Sie das Verzeichnis adk-samples/python/agents/travel-concierge.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/travel-concierge

4. Erstellen Sie einen neuen Cloud Storage-Bucket, der dem ADK AI-Agent gewidmet ist.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   Ersetzen Sie Folgendes:

   1. Ersetzen Sie CLOUD_STORAGE_BUCKET_NAME durch einen eindeutigen Bucket-Namen, den Sie verwenden möchten.
   2. PROJECT_ID durch die ID des Cloud-Projekts, das Sie erstellt haben.
   3. Ersetzen Sie PROJECT_LOCATION durch den Standort des von Ihnen erstellten Cloud-Projekts.

5. Legen Sie die folgenden Umgebungsvariablen fest:

   export GOOGLE_GENAI_USE_VERTEXAI=1
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_PLACES_API_KEY=PLACES_API_KEY
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
   export TRAVEL_CONCIERGE_SCENARIO=travel_concierge/profiles/itinerary_empty_default.json

   Ersetzen Sie Folgendes:

   1. PROJECT_ID durch die ID des Cloud-Projekts, das Sie erstellt haben.
   2. Ersetzen Sie PROJECT_LOCATION durch den Standort des von Ihnen erstellten Cloud-Projekts.
   3. PLACES_API_KEY durch den String des von Ihnen erstellten API-Schlüssels.
   4. CLOUD_STORAGE_BUCKET_NAME durch den Namen des Buckets, den Sie erstellt haben.

6. ADK AI-Agent installieren und bereitstellen

   uv sync --group deployment
   uv run python deployment/deploy.py --create

7. Rufen Sie die Projektnummer und die Engine-ID aus dem zuletzt gedruckten Log als PROJECT_NUMBER bzw. ENGINE_ID ab. Sie benötigen beide später, um Ihr Projekt zu konfigurieren.

   Created remote agent: projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENGINE_ID

Beispielcode ansehen

Bevor Sie das Projekt einrichten, können Sie sich optional den auf GitHub gehosteten Beispielcode ansehen.

Python

Auf GitHub ansehen

Apps Script

Auf GitHub ansehen

Projekt erstellen und konfigurieren

Python

1. Dieses GitHub-Repository herunterladen

   Herunterladen

2. Extrahieren Sie in Ihrer bevorzugten lokalen Entwicklungsumgebung die heruntergeladene Archivdatei und öffnen Sie das Verzeichnis add-ons-samples/python/travel-adk-ai-agent.

   unzip add-ons-samples-main.zip
   cd add-ons-samples-main/python/travel-adk-ai-agent

3. Verschieben Sie die JSON-Schlüsseldatei credentials.json aus dem Dienstkonto, das in den vorherigen Schritten heruntergeladen wurde, in das Projektverzeichnis.

4. Rufen Sie in der Google Cloud Console Cloud Run auf:

   Zu Cloud Run

5. Klicken Sie auf Schreiben Sie eine Funktion.

6. Richten Sie auf der Seite Dienst erstellen Ihre Funktion ein:

   1. Geben Sie im Feld Name des Dienstkontos travel-concierge-app ein.
   2. Wählen Sie in der Liste Region den Speicherort des Cloud-Projekts aus, das Sie erstellt haben, z. B. PROJECT_LOCATION.
   3. Klicken Sie unter Endpunkt-URL auf .
   4. Wählen Sie in der Liste Laufzeit die neueste Version von Python aus.
   5. Wählen Sie im Bereich Authentifizierung die Option Öffentlichen Zugriff erlauben aus.
   6. Klicken Sie im Bereich Container, Volumes, Netzwerk, Sicherheit unter Ressourcen auf
      .
      1. Wählen Sie im Feld Arbeitsspeicher die Option 1 GiB aus.
      2. Wählen Sie im Feld CPU die Option 2 aus.
   7. Klicken Sie auf Erstellen und warten Sie, bis der Dienst in Cloud Run erstellt wurde. Sie werden in der Console zum Tab Quelle weitergeleitet.

7. Stellen Sie den Quellcode des Projekts in Ihrer bevorzugten lokalen Entwicklungsumgebung bereit:

   gcloud run deploy travel-concierge-app --quiet --source . \
       --region PROJECT_LOCATION  \
       --function adk_ai_agent  \
       --set-env-vars LOCATION=LOCATION,PROJECT_NUMBER=PROJECT_NUMBER,ENGINE_ID=ENGINE_ID,BASE_URL=BASE_URL

   Ersetzen Sie Folgendes:

   1. PROJECT_LOCATION durch den Speicherort der zuvor erstellten Cloud Run-Funktion.
   2. LOCATION durch den Speicherort des Google Cloud-Projekts, das in den vorherigen Schritten erstellt wurde, PROJECT_LOCATION.
   3. PROJECT_NUMBER mit der Projektnummer des Travel Concierge ADK AI-Agents, der in den vorherigen Schritten bereitgestellt wurde.
   4. ENGINE_ID durch die Engine-ID des Travel Concierge ADK AI-Agents, der in den vorherigen Schritten bereitgestellt wurde.
   5. Ersetzen Sie BASE_URL durch die Endpunkt-URL, die Sie zuvor kopiert haben.

Apps Script

So erstellen Sie ein Apps Script-Projekt und konfigurieren es für die Verwendung Ihres bereitgestellten ADK-KI-Agents für den Reise-Concierge:

1. Klicken Sie auf die folgende Schaltfläche, um das Apps Script-Projekt Travel Concierge ADK AI Agent zu öffnen.
   Projekt öffnen

2. Klicken Sie auf  Übersicht und dann auf  Kopie erstellen.

3. Geben Sie Ihrer Kopie des Apps Script-Projekts einen Namen:

   1. Klicken Sie auf Copy of Travel Concierge ADK AI Agent (Kopie des ADK-KI-Agents für den Reise-Concierge).
   2. Geben Sie unter Projekttitel Travel Concierge ADK AI Agent ein.
   3. Klicken Sie auf Umbenennen.

4. Klicken Sie in Ihrem Apps Script-Projekt auf  Editor und verschieben Sie die Datei VertexAi.gs mit der Dateifunktion Datei nach oben verschieben nach oben, bis sie sich über der Datei AgentHandler.gs befindet.

5. Klicken Sie in Ihrem Apps Script-Projekt auf  Projekteinstellungen, dann auf Skripteigenschaften bearbeiten und schließlich auf Skripteigenschaft hinzufügen, um die folgenden Skripteigenschaften hinzuzufügen:

6. ENGINE_ID mit der Engine-ID des Travel Concierge ADK AI-Agents, der in den vorherigen Schritten bereitgestellt wurde, ENGINE_ID.

7. LOCATION durch den Standort des Google Cloud-Projekts, das in den vorherigen Schritten erstellt wurde, PROJECT_LOCATION.

8. PROJECT_NUMBER mit der Projektnummer des Travel Concierge ADK AI Agent, der in den vorherigen Schritten eingesetzt wurde, PROJECT_NUMBER.

9. SERVICE_ACCOUNT_KEY mit dem JSON-Schlüssel aus dem Dienstkonto, der in vorherigen Schritten heruntergeladen wurde, wie z. B. { ... }.

10. Klicken Sie auf Skripteigenschaften speichern.

11. Klicken Sie in Ihrem Apps Script-Projekt auf  Projekteinstellungen.

12. Klicken Sie unter Google Cloud Platform-Projekt (GCP-Projekt) auf Projekt ändern.

13. Fügen Sie unter GCP-Projektnummer die Projektnummer des in den vorherigen Schritten bereitgestellten Travel Concierge ADK AI Agent ein, PROJECT_NUMBER.

14. Klicken Sie auf Projekt festlegen. Das Cloud-Projekt und das Apps Script-Projekt sind jetzt verbunden.

Bereitstellung für Gmail, Google Kalender, Google Drive, Google Docs, Google Sheets und Google Präsentationen

Python

Verwenden Sie eine Google Workspace-Add‑on-Bereitstellung, um das Beispielprojekt in allen Google Workspace-Anwendungen (außer Google Chat) zu installieren, damit Sie es testen können.

1. Öffnen Sie in Ihrer bevorzugten lokalen Entwicklungsumgebung die Datei deployment.json aus dem Quellcode des Projekts und ersetzen Sie alle Vorkommen von $BASE_URL durch den Wert von BASE_URL, der Endpunkt-URL, die Sie in den vorherigen Schritten kopiert haben.

2. Erstellen Sie ein Google Workspace-Add-on-Deployment mit dem Namen travel-concierge-addon:

   gcloud workspace-add-ons deployments create travel-concierge-addon \
       --deployment-file=deployment.json

3. Installieren Sie die Google Workspace-Add-on-Bereitstellung:

   gcloud workspace-add-ons deployments install travel-concierge-addon

Apps Script

Installieren Sie das Apps Script-Projekt in allen Google Workspace-Anwendungen (außer Google Chat), um Tests zu ermöglichen.

1. Klicken Sie in Ihrem Apps Script-Projekt auf Bereitstellen > Bereitstellungen testen und dann auf Installieren.

Das Add-on ist jetzt über die Seitenleisten der Google Workspace-Anwendungen zugänglich.

In Google Chat bereitstellen

Python

Installieren Sie das Beispielprojekt in Chat, indem Sie die Endpunkt-URL verwenden, um Tests zu ermöglichen.

1. Suchen Sie in der Konsole nach Google Chat API, klicken Sie auf Google Chat API, dann auf Verwalten und Konfiguration.

   Zur Seite „Google Chat API-Konfiguration“

2. Chat App einrichten:

   1. Geben Sie im Feld App-Name den Namen Travel ADK AI Agent ein.
   2. Geben Sie im Feld Avatar-URL https://goo.gle/3SfMkjb ein.
   3. Geben Sie im Feld Beschreibung den Text Travel ADK AI Agent ein.
   4. Wählen Sie unter Verbindungseinstellungen die Option HTTP-Endpunkt-URL aus.
   5. Wählen Sie unter Trigger die Option Gemeinsame HTTP-Endpunkt-URL für alle Trigger verwenden aus.
   6. Fügen Sie in das Feld HTTP endpoint URL (HTTP-Endpunkt-URL) die Endpoint URL (Endpunkt-URL) ein, die Sie zuvor kopiert haben: BASE_URL.
   7. Registrieren Sie einen Schnellbefehl, der von der vollständig implementierten Chat-App verwendet wird:
      1. Klicken Sie unter Befehle auf Befehl hinzufügen.
      2. Geben Sie als Befehls-ID 1 ein.
      3. Geben Sie unter Beschreibung den Wert Reset session ein.
      4. Wählen Sie unter Befehlstyp die Option Schnellbefehl aus.
      5. Geben Sie unter Name den Wert Reset session ein.
      6. Klicken Sie auf Fertig. Der Schnellbefehl ist registriert und wird aufgeführt.
   8. Wählen Sie unter Sichtbarkeit die Option Diese Chat-App bestimmten Personen und Gruppen in Ihrer Workspace-Domain zur Verfügung stellen aus und geben Sie Ihre E-Mail-Adresse ein.
   9. Wählen Sie unter Logs die Option Fehler in Logging protokollieren aus.
   10. Klicken Sie auf Speichern.

Apps Script

Installieren Sie das Apps Script-Projekt in Chat mit der Head-Deployment-ID, um Tests zu ermöglichen.

1. Klicken Sie in Ihrem Apps Script-Projekt auf Bereitstellen > Bereitstellungen testen und dann unter Head-Bereitstellungs-ID auf  Kopieren.

2. Suchen Sie in der Konsole nach Google Chat API, klicken Sie auf Google Chat API, dann auf Verwalten und Konfiguration.

   Zur Seite „Google Chat API-Konfiguration“

3. Chat App einrichten:

   1. Geben Sie im Feld App-Name den Namen Travel ADK AI Agent ein.
   2. Geben Sie im Feld Avatar-URL https://goo.gle/3SfMkjb ein.
   3. Geben Sie im Feld Beschreibung den Text Travel ADK AI Agent ein.
   4. Wählen Sie unter Verbindungseinstellungen die Option Apps Script aus.
   5. Fügen Sie in das Feld Deployment ID (Deployment-ID) die Head deployment ID (Head-Deployment-ID) ein, die Sie zuvor kopiert haben.
   6. Registrieren Sie einen Schnellbefehl, der von der vollständig implementierten Chat-App verwendet wird:
      1. Klicken Sie unter Befehle auf Befehl hinzufügen.
      2. Geben Sie als Befehls-ID 1 ein.
      3. Geben Sie unter Beschreibung den Wert Reset session ein.
      4. Wählen Sie unter Befehlstyp die Option Schnellbefehl aus.
      5. Geben Sie unter Name den Wert Reset session ein.
      6. Klicken Sie auf Fertig. Der Schnellbefehl ist registriert und wird aufgeführt.
   7. Wählen Sie unter Sichtbarkeit die Option Diese Chat-App bestimmten Personen und Gruppen in Ihrer Workspace-Domain zur Verfügung stellen aus und geben Sie Ihre E-Mail-Adresse ein.
   8. Wählen Sie unter Logs die Option Fehler in Logging protokollieren aus.
   9. Klicken Sie auf Speichern.

Die App ist jetzt über Google Chat zugänglich.

1. Öffnen Sie Google Chat.

   Zu Google Chat wechseln

2. Chat-DM-Bereich erstellen:

   1. Klicken Sie auf  Neuer Chat.
   2. Geben Sie die App ein und wählen Sie sie in der Suche aus.Travel ADK AI Agent
   3. Klicken Sie im Dialogfeld Install app auf App installieren.
   4. Das Dialogfeld Install app wird geschlossen und der neu erstellte Chat-DM-Gruppenbereich wird ausgewählt.

Die Chat App ist bereit, auf Nachrichten zu antworten.

Agent testen

1. Öffnen Sie Google Mail.

   Zu Gmail gehen

2. Senden Sie die folgende E‑Mail an sich selbst:

   • Betreff: You need to travel to Paris
   • Body: Please be there between 11/25/2025 and 11/30/2025!

3. Öffnen Sie das Add‑on Travel ADK AI Agent über die Seitenleiste.

4. Klicken Sie auf Berechtigungen erteilen, um die Einrichtung des Add-ons abzuschließen.

5. Klicken Sie auf Senden, nachdem Sie die folgende Anfrage an den Agenten konfiguriert haben:

   • Nachricht:Please help me plan this travel!
   • Kontext:Wählen Sie Aktuelle E-Mail-Adresse aus.

   Die Seitenleiste wird mit der Antwort des Agenten aktualisiert.

   

6. Klicken Sie auf Chat öffnen, um zum Chat-DM-Bereich weitergeleitet zu werden.

7. Klicken Sie auf + > Sitzung zurücksetzen.

   Sie erhalten eine neue Nachricht, die bestätigt, dass der Vorgang abgeschlossen ist: OK, let's start from the beginning, what can I help you with?

8. Sende die Nachricht Give me ideas.

   Sie erhalten neue Nachrichten mit der Antwort des Kundenservicemitarbeiters.

   

9. Sende die Nachricht I want to go there!, nachdem du ein Bild von einem beliebigen Ort hochgeladen hast, z. B. Eiffelturm.

   Sie erhalten neue Nachrichten mit der Antwort des Kundenservicemitarbeiters.

   

Hinweis :Das Add-on Travel ADK AI Agent kann auch über die Seitenleiste in Kalender, Drive, Docs, Sheets und Präsentationen geöffnet werden, ähnlich wie in Gmail.

Beschränkungen

HTTP

In anderen Google Workspace-Anwendungen als Chat gelten für den KI-Agenten die folgenden Einschränkungen:

• Synchron: Die Seitenleisten können nur als Reaktion auf Nutzerinteraktionen aktualisiert werden. Die Antworten des KI-Agents werden daher erst nach Abschluss der Anfrage angezeigt (kein Streaming).

• Zeitüberschreitung möglich:Die Aktualisierung der Seitenleiste kann eine Zeitüberschreitung verursachen, wenn sie länger als einige Minuten dauert.

Diese Einschränkungen bestehen im Chat nicht.

Apps Script

In allen Google Workspace-Anwendungen ruft der KI-Agent Vertex AI REST APIs mit UrlFetchApp auf, was zu den folgenden Einschränkungen führt:

• Es ist synchron: Die Antworten des KI-Agenten werden erst nach vollständiger Fertigstellung zurückgegeben (kein Streaming).

• Zeitüberschreitung möglich:Bei KI-Agenten kann es zu einer Zeitüberschreitung kommen, wenn die Verarbeitung länger als etwa eine Minute dauert.

Anpassung

Diese Lösung unterstützt ADK AI-Agents, die in Vertex AI Agent Engine gehostet werden, eine Teilmenge der Google Workspace-Anwendungsoberflächen und Antwortdarstellungen, die speziell auf die Antworten des Travel Concierge-Beispiels zugeschnitten sind. Die Lösung basiert auf einem erweiterbaren Framework. Sie können sie anpassen, indem Sie die folgenden Dateien ändern:

Python

• main.py::Definiert die wichtigsten Benutzeroberflächen und die Logik für Nutzerinteraktionen (Google Workspace-Ereignishandler). Eine typische Erweiterung wäre die Aktivierung von Drive-Dokumenten als Kontextfunktion für die Drive-Anwendung, ähnlich wie dies mit Gmail-Nachrichten für die Gmail-Anwendung geschieht.

• vertex_ai.py: Verwaltet die Sitzungen, Antworten und Fehler des KI-Agenten und definiert Vertex AI-spezifische Schnittstellen zur Unterstützung von Agenteninteraktionen und Antwortdarstellungen. Typische Erweiterungen wären die Unterstützung von mehreren Sitzungen für separate Nutzerunterhaltungen und andere Plattformen zur Verwaltung von KI‑Agents.

• agent_handler.py: Implementiert Vertex AI-spezifische Schnittstellen, die in vertex_ai.py definiert sind, und zwar sowohl für Chat- als auch für Nicht-Chat-Anwendungen. Eine typische Erweiterung wäre das Hinzufügen von Schaltflächen, über die Nutzer Feedback zu den Antworten von KI-Agents geben können.

• google_workspace.py::Implementiert Interaktionen mit der Plattform zur Verwaltung von nicht KI-basierten Agents mithilfe von API-Aufrufen. In diesem Beispiel werden ausschließlich Google Workspace APIs verwendet, um Kontextinformationen zu erfassen und Aktionen durchzuführen. Eine typische Erweiterung wäre das Hinzufügen von Funktionen zum Abrufen von Geschäftsdaten aus Google Kalender oder einem CRM-System (Customer Relationship Management).

• travel_agent_ui_render.gs::Implementiert die spezifische Darstellung von Antworten für die untergeordneten Agents und Workspace-Anwendungen für Travel Concierge. Typische Erweiterungen wären die Unterstützung neuer Antwortdarstellungen, um Flugoptionen grafisch darzustellen, und anderer KI-Agents.

Apps Script

• Code.gs::Definiert die wichtigsten Benutzeroberflächen und die Logik für Nutzerinteraktionen (Google Workspace-Ereignishandler). Eine typische Erweiterung wäre die Aktivierung von Drive-Dokumenten als Kontextfunktion für die Drive-Anwendung, ähnlich wie dies mit Gmail-Nachrichten für die Gmail-Anwendung geschieht.

• VertexAi.gs::Verwaltet die Sitzungen, Antworten und Fehler des KI-Agents und definiert Vertex AI-spezifische Schnittstellen, die implementiert werden müssen, um Agent-Interaktionen und die Darstellung von Antworten zu unterstützen. Typische Erweiterungen wären die Unterstützung von mehreren Sitzungen für separate Nutzerunterhaltungen und andere Plattformen zur Verwaltung von KI‑Agents.

• AgentHandler.gs:Implementiert Vertex AI-spezifische Schnittstellen, die in VertexAi.gs für die spezifischen Fälle von Chat- und Nicht-Chat-Anwendungen definiert sind. Eine typische Erweiterung wäre das Hinzufügen von Schaltflächen, über die Nutzer Feedback zu den Antworten von KI-Agents geben können.

• GoogleWorkspace.gs::Implementiert Interaktionen mit der Agent-Verwaltungsplattform, die nicht auf KI basieren, mithilfe von API-Aufrufen. In diesem Beispiel werden ausschließlich Google Workspace APIs verwendet, um Kontextinformationen zu erfassen und Aktionen durchzuführen. Eine typische Erweiterung wäre das Hinzufügen von Funktionen zum Abrufen von Geschäftsdaten aus Google Kalender oder einem CRM-System (Customer Relationship Management).

• TravelAgentUiRender.gs::Implementiert die Darstellung von Antworten für die untergeordneten Agents und Workspace-Anwendungen, die speziell auf Travel Concierge zugeschnitten sind. Typische Erweiterungen wären die Unterstützung neuer Antwortdarstellungen, um Flugoptionen grafisch darzustellen, und anderer KI-Agents.

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. Um die URLs zu erhalten, die die Projekt-ID verwenden, wie z. B. eine URL auf appspot.com, löschen Sie die ausgewählten Ressourcen innerhalb des Projekts, anstatt das gesamte Projekt zu löschen.

Wenn Sie mehrere Tutorials und Schnellstartanleitungen durcharbeiten möchten, kann die Wiederverwendung von Projekten Ihnen helfen, die Projektkontingente nicht zu überschreiten.

1. Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten. Klicken Sie auf Menü > IAM & Admin > Ressourcen verwalten.

   Zum Ressourcenmanager

2. Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie dann auf Löschen .
3. Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie dann auf Herunterfahren, um das Projekt zu löschen.

Weitere Informationen

• Aussagen mit einem ADK-KI-Agenten und einem Gemini-Modell auf Fakten prüfen
• Grundlegende KI-Konzepte in Chat-Apps integrieren
• Chat-App als Google Workspace-Add‑on mit Apps Script erstellen