Planowanie podróży za pomocą agenta AI dostępnego w Google Workspace

Poziom kodowania: zaawansowany
Czas trwania: 45 minut
Typ projektu: Dodatek do Google Workspace rozszerzający Czat, Gmail, Kalendarz, Dysk, Dokumenty, Arkusze i Prezentacje.

Z tego samouczka dowiesz się, jak publikować agentów AI w Google Workspace jako dodatki do Google Workspace przy użyciu Apps Script lub punktów końcowych HTTP. Po opublikowaniu dodatku użytkownicy będą mogli korzystać z agentów AI w ramach swoich przepływów pracy.

Przegląd

W tym samouczku wdrożysz przykładowego agenta Travel Concierge z Agent Development Kit (ADK). Travel Concierge to konwersacyjna sztuczna inteligencja z wieloma agentami, która wykorzystuje takie narzędzia, jak Google Maps Platform Places API, Google Search Grounding i serwer Model Context Protocol (MCP).

ADK domyślnie udostępnia programistom interfejsy czatu i tekstowe. W tym samouczku dodasz graficzny interfejs użytkownika (GUI) do aplikacji Google Workspace, do którego użytkownicy będą mogli uzyskać dostęp bezpośrednio w Google Chat, Gmailu, Kalendarzu, na Dysku, w Dokumentach, Arkuszach i Prezentacjach.

• 

  Rysunek 1. Korzystanie z agenta AI z Chatu do burzy mózgów na temat pomysłów na podróże.

• 

  Rysunek 2. Korzystanie z agenta AI w Gmailu do planowania podróży na podstawie kontekstu wybranego e-maila.

Cele

• Skonfiguruj środowisko.
• Wdróż agenta AI.
• Skonfiguruj projekt.
• Wdrażaj w Gmailu, Kalendarzu, Dysku, Dokumentach, Arkuszach i Prezentacjach.
• Wdróż w czacie.
• Przetestuj rozwiązanie.

Informacje o rozwiązaniu

To rozwiązanie korzysta z tych podstawowych technologii: ADK, Google Cloud i interfejsów API Google Workspace, Vertex AI Agent Engine oraz platformy kart.

Interfejsy graficzne użytkownika (GUI) są projektowane inaczej w przypadku aplikacji obsługujących czat i aplikacji nieobsługujących czatu (Gmail, Kalendarz, Dysk, Dokumenty, Arkusze, Prezentacje), aby uwzględnić ich specyficzne funkcje i ograniczenia.

Funkcje

Poniższe funkcje aplikacji Travel Concierge są wspólne dla wszystkich aplikacji Google Workspace:

• Trwałe sesje użytkowników: sesje są zarządzane przez Vertex AI w celu zapewnienia trwałości. Każdy użytkownik współdzieli jedną sesję we wszystkich aplikacjach Workspace. Użytkownicy mogą ręcznie zresetować sesję, aby rozpocząć nową konwersację.

• Wiadomości z elementami multimedialnymi: użytkownicy wysyłają SMS-y i otrzymują odpowiedzi z tekstem sformatowanym i widgetami kart.

• Obsługa błędów: Nieoczekiwane błędy są obsługiwane w sposób prawidłowy dzięki konfigurowalnym ponownym próbom i statusom w odpowiedziach.

Aplikacja Czat ma następujące dodatkowe funkcje:

• Wielomodalne przesyłanie wiadomości użytkowników: Użytkownicy mogą wysyłać wiadomości z załącznikami, w tym nagraniami audio i wideo nagranymi bezpośrednio z przestrzeni czatu.

• Bardziej zaawansowane wizualnie odpowiedzi: Odpowiedzi można generować za pomocą bardziej zaawansowanych widżetów, takich jak karuzele z obrazami, korzystając z funkcji dostępnych wyłącznie w ramach czatu w ramach platformy Card oraz większej przestrzeni renderowania.

Inne aplikacje mają te dodatkowe funkcje:

• Kontekst profilu Google: Użytkownicy mogą wysyłać wiadomości zawierające informacje o swoim profilu (w tym przykładzie ograniczone do urodzin).

• Kontekst Gmaila: użytkownicy mogą wysyłać wiadomości z e-mailami (w tym przykładzie ograniczone do jednego tematu i treści).

• Dostęp do czatu agenta: Użytkownicy mogą otworzyć przestrzeń wiadomości bezpośrednich (DM) w aplikacji Czat w nowej karcie jednym kliknięciem przycisku.

Architektura

Aplikacja Travel Concierge odbiera i przetwarza zdarzenia interakcji dodatku do Google Workspace z aplikacji Google Workspace, używa Vertex AI do wywoływania agenta AI ADK i zarządzania sesjami użytkowników oraz korzysta z interfejsów API Google Cloud i Google Workspace, aby zbierać kontekst i wyświetlać odpowiedzi.

Na diagramie poniżej widać główny przepływ działań użytkownika: wysyłanie wiadomości do agenta AI.

HTTP

• 

  Rysunek 3. Aplikacja Chat uzupełnia kontekst za pomocą załączników z wiadomości użytkownika i wysyła zestaw wiadomości z historią interakcji z podagentem oraz ostateczną odpowiedzią w porządku chronologicznym.

• 

  Rysunek 4. Aplikacje inne niż czat uzupełniają kontekst o profil Google użytkownika i wybrane elementy, a także wyświetlają zestaw sekcji z historią interakcji podagentów i ostateczną ogólną odpowiedzią w odwrotnej kolejności chronologicznej.

Google Apps Script

• 

  Rysunek 3. Aplikacja Chat uzupełnia kontekst za pomocą załączników z wiadomości użytkownika i wysyła zestaw wiadomości z historią interakcji z podagentem oraz ostateczną odpowiedzią w porządku chronologicznym.

• 

  Rysunek 4. Aplikacja inna niż Chat uzupełnia kontekst o profil Google użytkownika i wybór produktu oraz wyświetla zestaw sekcji z historią interakcji z podagentem i ostateczną odpowiedzią w odwrotnej kolejności chronologicznej.

Wymagania wstępne

• Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.

• przeglądarkę internetową z dostępem do internetu,

• Wymagania wstępne dotyczące agenta AI ADK Travel Concierge

  • Python 3.10 lub nowszy: aby zainstalować Pythona, postępuj zgodnie z instrukcjami na oficjalnej stronie Pythona.
  • uv: Aby przeprowadzić instalację, postępuj zgodnie z instrukcjami na oficjalnej stronie uv.
  • Interfejs wiersza poleceń Google Cloud: aby go zainstalować, postępuj zgodnie z instrukcjami na oficjalnej stronie Google Cloud.

Przygotowywanie środowiska

W tej sekcji dowiesz się, jak utworzyć i skonfigurować projekt Google Cloud.

Tworzenie projektu Google Cloud

Konsola Google Cloud

1. W konsoli Google Cloud przejdź do menu > Zarządzanie dostępem i administracja > Utwórz projekt.

   Otwórz stronę Tworzenie projektu

2. W polu Nazwa projektu wpisz opisową nazwę projektu.

   Opcjonalnie: Aby edytować Identyfikator projektu, kliknij Edytuj. Po utworzeniu projektu nie można zmienić jego identyfikatora, więc wybierz taki, który będzie Ci odpowiadać przez cały okres jego istnienia.

3. W polu Lokalizacja kliknij Przeglądaj, aby wyświetlić potencjalne lokalizacje projektu. Następnie kliknij Wybierz.
   Uwaga: nie możesz znaleźć organizacji Google Workspace?
   Oznacza to, że nie korzystasz z konta Google Workspace. Niektóre funkcje opisane w dokumentacji dla deweloperów Google Workspace są dostępne tylko w projektach powiązanych z organizacją.
4. Kliknij Utwórz. W konsoli Google Cloud otworzy się strona Panel, a projekt zostanie utworzony w ciągu kilku minut.

interfejs wiersza poleceń gcloud

W jednym z następujących środowisk programistycznych uzyskaj dostęp do interfejsu wiersza poleceń Google Cloud (gcloud):

• Cloud Shell: Aby korzystać z terminala online z już skonfigurowanym interfejsem wiersza poleceń gcloud, aktywuj Cloud Shell.
  Aktywuj Cloud Shell
• Powłoka lokalna: aby użyć lokalnego środowiska programistycznego, zainstaluj i zainicjuj interfejs wiersza poleceń gcloud.
  Aby utworzyć projekt w chmurze, użyj polecenia gcloud projects create:

  gcloud projects create PROJECT_ID

  Zastąp PROJECT_ID identyfikatorem projektu, który chcesz utworzyć.

Włączanie płatności za projekt Cloud

Jeśli nie możesz połączyć konta rozliczeniowego, oznacza to, że nie masz uprawnień potrzebnych do wprowadzenia tej zmiany. Więcej informacji znajdziesz w artykule Uprawnienia wymagane do włączenia rozliczeń.

Konsola Google Cloud

1. W konsoli Google Cloud wybierz Płatności. Kliknij Menu > Rozliczenia > Moje projekty.

   Otwórz stronę Płatności za moje projekty

2. W sekcji Wybierz organizację wybierz organizację powiązaną z Twoim projektem Google Cloud.
3. W wierszu projektu otwórz menu Akcje (), kliknij Zmień rozliczenia i wybierz konto rozliczeniowe w chmurze.
4. Kliknij Ustaw konto.

interfejs wiersza poleceń gcloud

1. Aby wyświetlić listę dostępnych kont rozliczeniowych, uruchom to polecenie:

   gcloud billing accounts list

2. Połącz konto rozliczeniowe z projektem Google Cloud:

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

   Zastąp następujące elementy:

   • PROJECT_ID to identyfikator projektu projektu Cloud, w którym chcesz włączyć płatności.
   • BILLING_ACCOUNT_ID to identyfikator konta rozliczeniowego, które ma zostać połączone z projektem Google Cloud.

Włącz interfejsy API Google Cloud

HTTP

1. W konsoli Google Cloud włącz interfejsy API dodatków Vertex AI, Places, People, Google Chat, Gmail, Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry, Cloud Run i Google Workspace.

   Włączanie interfejsów API

2. Sprawdź, czy włączasz interfejsy API w odpowiednim projekcie w Cloud, a potem kliknij Dalej.

3. Sprawdź, czy włączasz odpowiednie interfejsy API, a potem kliknij Włącz.

Google Apps Script

1. W konsoli Google Cloud włącz interfejsy Vertex AI, Places, People i Google Chat API.

   Włączanie interfejsów API

2. Sprawdź, czy włączasz interfejsy API w odpowiednim projekcie w chmurze, a następnie kliknij Dalej.

3. Sprawdź, czy włączasz odpowiednie interfejsy API, a potem kliknij Włącz.

Uzyskiwanie klucza interfejsu Places API Google Maps Platform

1. W konsoli Google Cloud otwórz stronę Google Maps Platform > Klucze i dane logowania.

   Przejdź do Kluczy i uprawnień

2. W oknie dialogowym Rozpocznij korzystanie z platformy Google Maps Platform zostanie wyświetlony nowo utworzony klucz API — ciąg alfanumeryczny. Ten ciąg znaków będzie potrzebny w następnych sekcjach.

Uwaga: jeśli masz już odpowiedni klucz API, zostanie wyświetlona lista kluczy API, a nie okno dialogowe Rozpocznij korzystanie z platformy Google Maps Platform. WybieraćPokaż klucz aby wyświetlić klucz.

Utwórz konto usługi w konsoli Google Cloud

Utwórz nowe konto usługi z rolą Vertex AI User, wykonując następujące kroki:

Konsola Google Cloud

1. W konsoli Google Cloud przejdź do menu > Zarządzanie dostępem i administracja > Konta usług.

   Otwórz stronę Konta usługi

2. Kliknij Utwórz konto usługi.
3. Wypełnij dane konta usługi, a następnie kliknij Utwórz i kontynuuj.
   Uwaga: domyślnie Google tworzy unikalny identyfikator konta usługi. Jeśli chcesz zmienić identyfikator, zmodyfikuj go w polu Identyfikator konta usługi.
4. Opcjonalnie: przypisz role do konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie uprawnień dostępu do zasobów.
5. Kliknij Dalej.
6. Opcjonalnie: wprowadź użytkowników lub grupy, które mogą zarządzać tym kontem usługi i wykonywać za jego pomocą działania. Aby uzyskać więcej informacji, zapoznaj się z artykułem Zarządzanie podszywaniem się pod konto usługi.
7. Kliknij Gotowe. Zanotuj adres e-mail konta usługi.

interfejs wiersza poleceń gcloud

1. Utwórz konto usługi:

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

2. Opcjonalnie: przypisz role do konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Aby uzyskać więcej informacji, zapoznaj się z sekcją Przyznawanie, zmienianie i cofanie dostępu do zasobów.

Konto usługi jest widoczne na stronie konta usługi. Następnie utwórz klucz prywatny dla konta usługi.

Tworzenie klucza prywatnego

Ostrzeżenie: W celu uproszczenia w tym przykładzie użyto wyeksportowanego klucza konta usługi. Nie zaleca się eksportowania klucza prywatnego w środowisku produkcyjnym, ponieważ nie powinien być on przechowywany w niezabezpieczonej lokalizacji, takiej jak system kontroli źródła.

Aby dowiedzieć się więcej o bezpiecznych wdrożeniach kont usług i najlepszych praktykach, zobacz Wybór momentu korzystania z kont usług.

Aby utworzyć i pobrać klucz prywatny dla konta usługi, wykonaj następujące kroki:

1. W konsoli Google Cloud przejdź do menu > Zarządzanie dostępem i administracja > Konta usług.

   Otwórz stronę Konta usługi

2. Wybierz konto usługi.
3. Kliknij Klucze > Dodaj klucz > Utwórz nowy klucz.
4. Wybierz JSON, a potem kliknij Utwórz.

   Nowa para kluczy publicznych/prywatnych zostanie wygenerowana i pobrana na Twoje urządzenie jako nowy plik. Zapisz pobrany plik JSON jako credentials.json w katalogu roboczym. Jest to jedyna kopia tego klucza. Informacje o tym, jak bezpiecznie przechowywać klucz, znajdziesz w artykule Zarządzanie kluczami konta usługi.

5. Kliknij Zamknij.

Więcej informacji o kontach usług znajdziesz w dokumentacji kont usług Google Cloud IAM.

Skonfiguruj ekran zgody OAuth

Dodatki do Google Workspace wymagają konfiguracji ekranu zgody. Skonfigurowanie ekranu zgody OAuth dodatku określa, co Google wyświetla użytkownikom.

1. W konsoli Google Cloud otwórz Menu  > Google Auth platform > Branding.

   Otwórz Promowanie marki

2. Jeśli skonfigurowano już Google Auth platform, można skonfigurować następujące ustawienia ekranu zgody OAuth w sekcjach Branding, Odbiorcy i Dostęp do danych. Jeśli zobaczysz komunikat Google Auth platform nie skonfigurowano jeszcze, kliknij Rozpocznij:
1. W obszarze Informacje o aplikacji, w polu Nazwa aplikacji wpisz nazwę aplikacji.
2. W polu Adres e-mail dla użytkowników potrzebujących pomocy wybierz adres e-mail, na który użytkownicy mogą pisać, aby się z Tobą skontaktować w sprawie pytań o ich zgodę.
3. Kliknij Dalej.
4. W sekcji Odbiorcy wybierz Wewnętrzny.
5. Kliknij Dalej.
6. W sekcji Dane kontaktowe wpisz adres e-mail, na który będziesz otrzymywać powiadomienia o zmianach w projekcie.
7. Kliknij Dalej.
8. W obszarze Zakończ zapoznaj się z Zasadami dotyczącymi danych użytkownika w usługach interfejsu API Google i jeśli się z nimi zgadzasz, wybierz opcję Akceptuję Zasady dotyczące danych użytkownika w usługach interfejsu API Google.
9. Kliknij Dalej.
10. Kliknij Utwórz.
3. Na razie możesz pominąć dodawanie zakresów. W przyszłości, gdy będziesz tworzyć aplikację przeznaczoną do użytku poza Twoją organizacją Google Workspace, musisz zmienić Typ użytkownika na Zewnętrzny. Następnie dodaj zakresy autoryzacji wymagane przez Twoją aplikację. Aby dowiedzieć się więcej, zapoznaj się z pełnym przewodnikiem Konfigurowanie zgody OAuth.

Wdróż agenta AI Travel Concierge ADK

1. Jeśli jeszcze tego nie zrobiłeś, uwierzytelnij się przy użyciu konta Google Cloud i skonfiguruj interfejs wiersza poleceń Google Cloud CLI, aby korzystać z projektu Google Cloud.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   Zastąp PROJECT_ID identyfikatorem utworzonego projektu w chmurze.

2. Pobierz to repozytorium GitHub

   Pobierz

3. W preferowanym lokalnym środowisku programistycznym wypakuj pobrany plik archiwum i otwórz katalog adk-samples/python/agents/travel-concierge.

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

4. Utwórz nowy kontener Cloud Storage dedykowany agentowi ADK AI.

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

   Zastąp następujące elementy:

   1. CLOUD_STORAGE_BUCKET_NAME z unikalną nazwą kontenera, której chcesz użyć.
   2. PROJECT_ID z identyfikatorem projektu w chmurze, który utworzyłeś.
   3. PROJECT_LOCATION z lokalizacją utworzonego projektu w chmurze.

5. Ustaw następujące zmienne środowiskowe:

   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

   Zastąp następujące elementy:

   1. PROJECT_ID z identyfikatorem utworzonego projektu Cloud.
   2. PROJECT_LOCATION z lokalizacją utworzonego przez Ciebie projektu w chmurze.
   3. PLACES_API_KEY ciągiem utworzonego klucza interfejsu API.
   4. CLOUD_STORAGE_BUCKET_NAME nazwą utworzonego zasobnika.

6. Zainstaluj i wdróż agenta ADK AI.

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

7. Pobierz numer projektu i identyfikator silnika z ostatniego wydrukowanego dziennika odpowiednio jako PROJECT_NUMBER i ENGINE_ID. Oba będą Ci potrzebne później do skonfigurowania projektu.

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

Sprawdź przykładowy kod

Opcjonalnie przed skonfigurowaniem projektu poświęć chwilę na zapoznanie się z przykładowym kodem hostowanym na GitHubie.

Python

Wyświetl w GitHubie

Google Apps Script

Wyświetl w GitHubie

Tworzenie i konfigurowanie projektu

Python

1. Pobierz to repozytorium GitHub

   Pobierz

2. W preferowanym lokalnym środowisku programistycznym wypakuj pobrany plik archiwum i otwórz katalog 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. Przenieś plik klucza JSON credentials.json z konta usługi pobranego w poprzednich krokach do katalogu projektu.

4. W konsoli Google Cloud otwórz Cloud Run:

   Otwórz Cloud Run

5. Kliknij Napisz funkcję.

6. Na stronie Utwórz usługę skonfiguruj funkcję:

   1. W polu Nazwa usługi wpisz travel-concierge-app.
   2. Na liście Region wybierz lokalizację utworzonego projektu w Cloud, PROJECT_LOCATION.
   3. W obszarze Adres URL punktu końcowego kliknij .
   4. Na liście Środowisko wykonawcze wybierz najnowszą wersję Pythona.
   5. W sekcji Uwierzytelnianie wybierz opcję Zezwalaj na dostęp publiczny.
   6. W sekcji Kontenery, woluminy, sieć, zabezpieczenia w obszarze Zasoby:
      1. W polu Pamięć wybierz 1 GiB.
      2. W polu CPU wybierz 2.
   7. Kliknij Utwórz i poczekaj, aż Cloud Run utworzy usługę. Konsola przekieruje Cię na kartę Źródło.

7. W preferowanym lokalnym środowisku programistycznym wdróż kod źródłowy projektu:

   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

   Zastąp następujące elementy:

   1. PROJECT_LOCATION z lokalizacją utworzonej wcześniej funkcji Cloud Run.
   2. LOCATION z lokalizacją projektu Google Cloud utworzonego w poprzednich krokach: PROJECT_LOCATION.
   3. PROJECT_NUMBER z numerem projektu agenta AI Travel Concierge ADK wdrożonego w poprzednich krokach.
   4. ENGINE_ID z identyfikatorem silnika agenta AI Travel Concierge ADK wdrożonego w poprzednich krokach.
   5. BASE_URL z adresem URL punktu końcowego, który wcześniej skopiowałeś.

Google Apps Script

Aby utworzyć projekt Apps Script i skonfigurować go do korzystania z wdrożonego agenta Travel Concierge ADK AI:

1. Kliknij ten przycisk, aby otworzyć projekt Travel Concierge ADK AI Agent Apps Script.
   Otwórz projekt

2. Kliknij Przegląd, a następnie Utwórz kopię.

3. Nadaj nazwę swojej kopii projektu Apps Script:

   1. Kliknij Kopia agenta AI Travel Concierge ADK.
   2. W polu Nazwa projektu wpisz Travel Concierge ADK AI Agent.
   3. Kliknij Zmień nazwę.

4. W projekcie Apps Script kliknij Edytor i przenieś plik VertexAi.gs w górę, aż znajdzie się nad plikiem AgentHandler.gs, używając akcji Przenieś plik w górę.

5. W projekcie Apps Script kliknij Ustawienia projektu, kliknij Edytuj właściwości skryptu, a następnie kliknij Dodaj właściwość skryptu, aby dodać następujące właściwości skryptu:

6. ENGINE_ID z identyfikatorem silnika agenta AI Travel Concierge ADK wdrożonego w poprzednich krokach, ENGINE_ID.

7. LOCATION z lokalizacją projektu Google Cloud utworzonego w poprzednich krokach, PROJECT_LOCATION.

8. PROJECT_NUMBER z numerem projektu AI ADK Travel Concierge, PROJECT_NUMBER, który został wdrożony w poprzednich krokach.

9. SERVICE_ACCOUNT_KEY z kluczem JSON z konta usługi pobranego w poprzednich krokach, takich jak { ... }.

10. Kliknij Zapisz właściwości skryptu

11. W projekcie Apps Script kliknij  Ustawienia projektu.

12. W sekcji Projekt Google Cloud Platform (GCP) kliknij Zmień projekt.

13. W polu Numer projektu GCP wklej numer projektu agenta AI Travel Concierge ADK wdrożonego w poprzednich krokach: PROJECT_NUMBER.

14. Kliknij Ustaw projekt. Projekt w chmurze i projekt Apps Script są teraz połączone.

Wdrażanie w Gmailu, Kalendarzu, Dysku, Dokumentach, Arkuszach i Prezentacjach

Python

Użyj wdrożenia dodatku do Google Workspace, aby zainstalować przykładowy projekt we wszystkich aplikacjach Google Workspace (z wyjątkiem Google Chat), aby umożliwić testowanie.

1. W wybranym lokalnym środowisku programistycznym otwórz plik deployment.json ze źródła kodu projektu i zastąp wszystkie wystąpienia $BASE_URL wartością BASE_URL, czyli adresem URL punktu końcowego skopiowanym w poprzednich krokach.

2. Utwórz wdrożenie dodatku Google Workspace o nazwie travel-concierge-addon:

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

3. Zainstaluj wdrożenie dodatku do Google Workspace:

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

Google Apps Script

Zainstaluj projekt Apps Script we wszystkich aplikacjach Google Workspace (oprócz Google Chat), aby umożliwić testowanie.

1. W projekcie Apps Script kliknij Wdróż > Przetestuj wdrożenia, a następnie Zainstaluj.

Dodatek jest teraz dostępny na paskach bocznych aplikacji Google Workspace.

Wdrażanie w Google Chat

Python

Zainstaluj przykładowy projekt w Google Chat, używając adresu URL punktu końcowego, aby włączyć testowanie.

1. W konsoli wyszukaj Google Chat API, kliknij Google Chat API, a następnie Zarządzaj i Konfiguracja.

   Przejdź do strony konfiguracji interfejsu API Google Chat

2. Skonfiguruj aplikację Google Chat:

   1. W polu Nazwa aplikacji wpisz Travel ADK AI Agent.
   2. W polu Avatar URL (Adres URL awatara) wpisz https://goo.gle/3SfMkjb.
   3. W polu Opis wpisz Travel ADK AI Agent.
   4. W sekcji Ustawienia połączenia kliknij URL punktu końcowego HTTP.
   5. W sekcji Aktywatory kliknij Używaj wspólnego adresu URL punktu końcowego HTTP dla wszystkich aktywatorów.
   6. W polu HTTP endpoint URL (Adres URL punktu końcowego HTTP) wklej skopiowany wcześniej Endpoint URL (Adres URL punktu końcowego)BASE_URL.
   7. Zarejestruj szybkie polecenie, z którego korzysta w pełni wdrożona aplikacja czatu:
      1. W obszarze Polecenia kliknij Dodaj polecenie.
      2. W polu Identyfikator polecenia wpisz 1.
      3. W polu Opis wpisz Reset session.
      4. W sekcji Typ polecenia kliknij Szybkie polecenie.
      5. W polu Nazwa wpisz Reset session.
      6. Kliknij Gotowe. Szybkie polecenie zostanie zarejestrowane i wyświetlone na liście.
   8. W sekcji Widoczność wybierz Udostępnij tę aplikację do obsługi czatu konkretnym osobom i grupom w domenie Workspace i wpisz swój adres e-mail.
   9. W sekcji Logi wybierz Loguj błędy w usłudze Logging.
   10. Kliknij Zapisz.

Google Apps Script

Zainstaluj projekt Apps Script w czacie, używając identyfikatora wdrożenia Head, aby umożliwić testowanie.

1. W projekcie Apps Script kliknij Wdrażanie > Testowanie wdrożeń , Następnie Kopia pod Identyfikator wdrożenia głównego.

2. W konsoli wyszukaj Google Chat API, kliknij API Google Chat, następnie Zarządzaj i Konfiguracja.

   Przejdź do strony konfiguracji interfejsu API Google Chat

3. Skonfiguruj aplikację Google Chat:

   1. W polu Nazwa aplikacji wpisz Travel ADK AI Agent.
   2. W polu Avatar URL (Adres URL awatara) wpisz https://goo.gle/3SfMkjb.
   3. W polu Opis wpisz Travel ADK AI Agent.
   4. W obszarze Ustawienia połączenia wybierz opcję Apps Script.
   5. W polu Identyfikator wdrożenia wklej wcześniej skopiowany Identyfikator wdrożenia Head.
   6. Zarejestruj szybkie polecenie, z którego korzysta w pełni wdrożona aplikacja czatu:
      1. W sekcji Polecenia kliknij Dodaj polecenie.
      2. W polu Identyfikator polecenia wpisz 1.
      3. W polu Opis wpisz Reset session.
      4. W sekcji Typ polecenia kliknij Szybkie polecenie.
      5. W polu Nazwa wpisz Reset session.
      6. Kliknij Gotowe. Szybkie polecenie zostanie zarejestrowane i wyświetlone na liście.
   7. W sekcji Widoczność wybierz Udostępnij tę aplikację do obsługi czatu konkretnym osobom i grupom w domenie Workspace i wpisz swój adres e-mail.
   8. W sekcji Logi wybierz Loguj błędy w usłudze Logging.
   9. Kliknij Zapisz.

Aplikacja jest teraz dostępna w Google Chat.

1. Otwórz Google Chat.

   Otwórz Google Chat

2. Utwórz pokój czatu DM:

   1. Kliknij Nowy czat.
   2. Wpisz i wybierz aplikację Travel ADK AI Agent w wyszukiwarce.
   3. W oknie dialogowym Install app kliknij Zainstaluj aplikację.
   4. Okno dialogowe Install app zostanie zamknięte i wybrany zostanie nowo utworzony pokój czatu DM.

Aplikacja Chat jest gotowa do odpowiadania na wiadomości.

Testowanie agenta

1. Otwórz aplikację Gmail.

   Otwórz Gmaila

2. Wyślij do siebie tego e-maila:

   • Temat: You need to travel to Paris
   • Treść: Please be there between 11/25/2025 and 11/30/2025!

3. Otwórz dodatek Travel ADK AI Agent na pasku bocznym.

4. Aby dokończyć konfigurację dodatku, kliknij Przyznaj uprawnienia.

5. Po skonfigurowaniu poniższego żądania do agenta kliknij Wyślij:

   • Wiadomość: Please help me plan this travel!
   • Kontekst: wybierz Obecny adres e-mail.

   Pasek boczny zostanie zaktualizowany odpowiedzią agenta.

   

6. Kliknij Otwórz Google Chat, aby przejść do pokoju czatu.

7. Kliknij + > Resetuj sesję.

   Otrzymasz nową wiadomość z potwierdzeniem: OK, let's start from the beginning, what can I help you with?

8. Wyślij wiadomość Give me ideas.

   Otrzymasz nowe wiadomości z odpowiedzią agenta.

   

9. Wyślij wiadomość I want to go there! po przesłaniu zdjęcia dowolnego miejsca, takiego jak Wieża Eiffla.

   Otrzymujesz nowe wiadomości wraz z odpowiedziami agenta.

   

Uwaga: dodatek Travel ADK AI Agent można też otworzyć na pasku bocznym w Kalendarzu, na Dysku, w Dokumentach, Arkuszach i Prezentacjach, podobnie jak w Gmailu.

Ograniczenia

HTTP

W aplikacjach Google Workspace innych niż Chat agent AI ma następujące ograniczenia:

• Jest synchroniczny: paski boczne można aktualizować tylko w odpowiedzi na interakcje użytkownika, więc odpowiedzi agenta AI są wyświetlane dopiero po pełnym zakończeniu (bez przesyłania strumieniowego).

• Może nastąpić przekroczenie limitu czasu: aktualizacje paska bocznego ulegają przekroczeniu limitu czasu, jeśli ich ukończenie zajmuje więcej niż kilka minut.

W przypadku Czatu te ograniczenia nie występują.

Google Apps Script

We wszystkich aplikacjach Google Workspace agent AI wywołuje interfejsy API REST Vertex AI przy użyciu UrlFetchApp, co powoduje następujące ograniczenia:

• Jest synchroniczny: odpowiedzi agenta AI są zwracane dopiero po całkowitym zakończeniu (bez przesyłania strumieniowego).

• Może nastąpić przekroczenie limitu czasu: Agent AI żąda przekroczenia limitu czasu, gdy jego ukończenie zajmuje więcej niż minutę.

Dostosowywanie

To rozwiązanie obsługuje agentów ADK AI hostowanych w Vertex AI Agent Engine, podzbiór interfejsów użytkownika aplikacji Google Workspace oraz renderowanie odpowiedzi specyficzne dla odpowiedzi przykładu Travel Concierge. Rozwiązanie korzysta z rozszerzalnej struktury, więc możesz je dostosować, modyfikując te pliki:

Python

• main.py: definiuje główne interfejsy i logikę interakcji użytkownika (obsługę zdarzeń Google Workspace). Typowym rozszerzeniem byłoby włączenie dokumentów Dysku jako funkcji kontekstowej w aplikacji Dysk, podobnie jak zrobiono to w przypadku wiadomości Gmail w aplikacji Gmail.

• vertex_ai.py: zarządza sesjami, odpowiedziami i błędami agenta AI oraz definiuje interfejsy specyficzne dla Vertex AI, które należy wdrożyć, aby obsługiwać interakcje z agentem i renderowanie odpowiedzi. Typowe rozszerzenia obejmowałyby dodanie obsługi wielu sesji dla oddzielnych rozmów użytkowników i innych platform zarządzania agentami AI.

• agent_handler.py: Implementuje interfejsy specyficzne dla Vertex AI zdefiniowane w pliku vertex_ai.py w określonych przypadkach aplikacji czatu i innych niż czat. Typowym rozszerzeniem byłoby dodanie przycisków umożliwiających użytkownikom wysyłanie opinii na temat odpowiedzi agentów AI.

• google_workspace.py: implementuje interakcje platformy zarządzania agentami bez AI za pomocą wywołań interfejsu API. W tym przykładzie do zbierania szczegółów kontekstu i podejmowania działań używane są tylko interfejsy API Google Workspace. Typowym rozszerzeniem byłoby dodanie funkcji pobierania danych o firmie z Kalendarza Google lub systemu zarządzania relacjami z klientami (CRM).

• travel_agent_ui_render.gs: implementuje renderowanie odpowiedzi specyficznych dla usługi Travel Concierge w przypadku subagentów i aplikacji Workspace. Typowe rozszerzenia to dodanie obsługi nowych sposobów renderowania odpowiedzi, aby graficznie wyświetlać opcje lotów i inne agenty AI.

Google Apps Script

• Code.gs: Definiuje główne interfejsy użytkownika i logikę interakcji użytkownika (obsługa zdarzeń Google Workspace). Typowym rozszerzeniem byłoby włączenie dokumentów Dysku jako funkcji kontekstowej w aplikacji Dysk, podobnie jak zrobiono to w przypadku wiadomości Gmail w aplikacji Gmail.

• VertexAi.gs: zarządza sesjami, odpowiedziami i błędami agenta AI oraz definiuje interfejsy specyficzne dla Vertex AI, które należy wdrożyć, aby obsługiwać interakcje z agentem i renderowanie odpowiedzi. Typowe rozszerzenia to dodanie obsługi wielu sesji dla oddzielnych rozmów użytkowników i innych platform do zarządzania agentami AI.

• AgentHandler.gs: Implementuje interfejsy specyficzne dla Vertex AI zdefiniowane w VertexAi.gs w określonych przypadkach aplikacji czatu i innych niż czat. Typowym rozszerzeniem byłoby dodanie przycisków, za pomocą których użytkownicy mogliby przesyłać opinie o odpowiedziach agenta AI.

• GoogleWorkspace.gs: implementuje interakcje z platformą zarządzania agentami bez AI za pomocą wywołań interfejsu API. W tym przykładzie do zbierania szczegółów kontekstu i podejmowania działań używane są tylko interfejsy API Google Workspace. Typowym rozszerzeniem byłoby dodanie funkcji pobierania danych o firmie z Kalendarza Google lub systemu zarządzania relacjami z klientami (CRM).

• TravelAgentUiRender.gs: implementuje renderowanie odpowiedzi specyficznych dla usługi Travel Concierge w przypadku subagentów i aplikacji Workspace. Typowe rozszerzenia to dodanie obsługi nowych sposobów renderowania odpowiedzi, aby graficznie wyświetlać opcje lotów i inne agenty AI.

Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby zużyte w tym samouczku, zalecamy usunięcie projektu w Cloud.

Ostrzeżenie: usunięcie projektu spowoduje, że:

• Wszystkie dane projektu zostaną usunięte. Jeśli na potrzeby tego samouczka został przez Ciebie użyty istniejący projekt, po jego usunięciu usuniesz też wszystkie inne wykonane w nim zadania.
• Niestandardowe identyfikatory projektu zostaną utracone. Podczas tworzenia tego projektu możesz utworzyć niestandardowy identyfikator projektu, którego chcesz używać w przyszłości. Aby zachować adresy URL, które używają identyfikatora projektu, np. adres URL w domenie appspot.com, usuń wybrane zasoby w projekcie zamiast usuwać cały projekt.

Jeśli zamierzasz skorzystać z innych samouczków i krótkich wprowadzeń, ponowne wykorzystanie tych samych projektów może pomóc Ci uniknąć przekroczenia Iimitów związanych z projektami.

1. W konsoli Google Cloud otwórz stronę Zarządzanie zasobami. Kliknij Menu > Administracja > Zarządzaj zasobami.

   Otwórz Menedżera zasobów

2. Z listy projektów wybierz projekt do usunięcia, a potem kliknij Usuń .
3. W oknie dialogowym wpisz identyfikator projektu, a następnie kliknij Zamknij, aby usunąć projekt.

Powiązane artykuły

• Sprawdzanie faktów za pomocą agenta AI ADK i modelu Gemini
• Zintegruj podstawowe koncepcje sztucznej inteligencji z aplikacjami do czatów
• Tworzenie aplikacji do czatu jako dodatku do Google Workspace za pomocą Apps Script