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

Poziom kodowania: zaawansowany
Czas trwania: 45 minut
Rodzaj projektu: dodatek do Google Workspace rozszerzający Chat, Gmail, Kalendarz, Dysk oraz Dokumenty, Arkusze i Prezentacje.

Z tego samouczka dowiesz się, jak publikować agenty 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 wchodzić w interakcje z agentami AI w ramach swoich przepływów pracy.

Przegląd

W tym samouczku wdrożysz przykładowego agenta Travel Concierge z pakietu Agent Development Kit (ADK). Travel Concierge to konwersacyjna agentowa AI oparta na wielu agentach, która korzysta z narzędzi takich jak interfejs Places API w Google Maps Platform, Google Search Grounding i serwer Model Context Protocol (MCP).

ADK domyślnie udostępnia programistom interfejsy czatu i tekstowe. W tym samouczku dodasz do aplikacji Google Workspace graficzny interfejs użytkownika, 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.

  • Korzystanie z agenta AI w Chat do burzy mózgów na temat pomysłów na podróż.
    Rysunek 1. Korzystanie z agenta AI w Google Chat do przeprowadzenia burzy mózgów na temat pomysłów na podróż.
  • Korzystanie z agenta AI w Gmailu do planowania podróży na podstawie kontekstu wybranego e-maila.
    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żanie w Gmailu, Kalendarzu, Dysku, Dokumentach, Arkuszach i Prezentacjach.
  • Wdróż w Google Chat.
  • Przetestuj rozwiązanie.

Informacje o rozwiązaniu

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

Interfejsy GUI są zaprojektowane inaczej w przypadku aplikacji Chat i aplikacji innych niż Chat (Gmail, Kalendarz, Dysk, Dokumenty, Arkusze, Prezentacje), aby uwzględnić ich specyficzne funkcje i ograniczenia.

Funkcje

Te 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 ma jedną sesję we wszystkich aplikacjach Workspace. Użytkownicy mogą ręcznie zresetować sesję, aby rozpocząć nową rozmowę.

  • 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 stanom w odpowiedziach.

Aplikacja Google Chat ma te dodatkowe funkcje:

  • Wielomodalne wiadomości użytkowników: użytkownicy mogą wysyłać wiadomości z załącznikami, w tym nagrania audio i wideo bezpośrednio z pokoju w Google Chat.

  • Bardziej zaawansowane wizualnie odpowiedzi: odpowiedzi mogą być generowane za pomocą bardziej zaawansowanych widżetów, takich jak karuzele ze zdjęciami, dzięki wykorzystaniu funkcji frameworka kart przeznaczonych tylko do czatu i większej przestrzeni renderowania.

Inne aplikacje mają te dodatkowe funkcje:

  • Kontekst profilu Google: użytkownicy mogą wysyłać wiadomości z informacjami z profilu (w tym przykładzie ograniczonymi do daty urodzenia).

  • 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 agenta do czatu: użytkownicy mogą otworzyć czat w aplikacji Google Chat na nowej karcie jednym kliknięciem.

Architektura

Aplikacja Travel Concierge odbiera i przetwarza zdarzenia interakcji dodatku 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 Google Cloud i Google Workspace API, aby zbierać kontekst i wyświetlać odpowiedzi.

Na diagramie poniżej przedstawiono główny wzorzec przeglądania: wysyłanie wiadomości do agenta AI.

HTTP

  • Schemat architektury aplikacji Google Chat.
    Rysunek 3. Aplikacja Google Chat uzupełnia kontekst za pomocą załączników z wiadomości użytkownika i wysyła zestaw wiadomości z historią interakcji z subagentem oraz ostateczną ogólną odpowiedzią w porządku chronologicznym.
  • Schemat architektury aplikacji innych niż Chat.
    Rysunek 4. Aplikacja inna niż Chat uzupełnia kontekst o profil Google użytkownika i wybór produktu, a następnie wyświetla zestaw sekcji z historią interakcji z podagentem i ostateczną odpowiedzią w odwrotnej kolejności chronologicznej.

Google Apps Script

  • Schemat architektury aplikacji Google Chat.
    Rysunek 3. Aplikacja Google Chat uzupełnia kontekst za pomocą załączników z wiadomości użytkownika i wysyła zestaw wiadomości z historią interakcji z subagentem oraz ostateczną ogólną odpowiedzią w porządku chronologicznym.
  • Schemat architektury aplikacji innych niż Chat.
    Rysunek 4. Aplikacja inna niż Chat uzupełnia kontekst o profil Google użytkownika i wybór produktu, a następnie wyświetla zestaw sekcji z historią interakcji z podagentem i ostateczną odpowiedzią w odwrotnej kolejności chronologicznej.

Wymagania wstępne

Przygotowywanie środowiska

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

Tworzenie projektu Google Cloud

Konsola interfejsów API Google

  1. W konsoli interfejsów API Google otwórz Menu  > Uprawnienia i administracja > Utwórz projekt.

    Otwórz stronę Tworzenie projektu

  2. W polu Project Name (Nazwa projektu) wpisz nazwę opisową projektu.

    Opcjonalnie: aby edytować identyfikator projektu, kliknij Edytuj. Po utworzeniu projektu nie można zmienić identyfikatora projektu, dlatego wybierz identyfikator, który będzie odpowiadać Twoim potrzebom przez cały okres istnienia projektu.

  3. W polu Lokalizacja kliknij Przeglądaj, aby wyświetlić potencjalne lokalizacje projektu. Następnie kliknij Wybierz.
  4. Kliknij Utwórz. Konsola interfejsów API Google przekieruje Cię na stronę Panel, a projekt zostanie utworzony w ciągu kilku minut.

interfejs wiersza poleceń gcloud

W jednym z tych środowisk programistycznych uzyskaj dostęp do interfejsu Google Cloud CLI (gcloud):

  • Cloud Shell: aby używać terminala online z już skonfigurowanym interfejsem gcloud CLI, aktywuj Cloud Shell.
    Aktywuj Cloud Shell
  • Lokalna powłoka: aby używać 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 w chmurze

Konsola interfejsów API Google

  1. W Konsoli interfejsów API Google otwórz Rozliczenia. 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 Działania , kliknij Zmień ustawienia płatności i wybierz konto rozliczeniowe Cloud.
  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 te elementy:

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

Włączanie interfejsów Google Cloud APIs

HTTP

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

    Włączanie interfejsów API

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

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

Google Apps Script

  1. W Konsoli interfejsów API Google włącz interfejsy Vertex AI, Miejsca, People, Google Chat i Cloud Resource Manager API.

    Włączanie interfejsów API

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

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

Uzyskiwanie klucza interfejsu API Places Google Maps Platform

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

    Otwórz stronę Klucze i dane logowania

  2. W oknie Pierwsze kroki w Google Maps Platform pojawi się nowo utworzony klucz interfejsu API, czyli ciąg znaków alfanumerycznych. Ten ciąg znaków będzie Ci potrzebny w następnych sekcjach.

Tworzenie konta usługi w konsoli Google Cloud

Utwórz nowe konto usługi z rolą Vertex AI User, wykonując te czynności:

Google Cloud Console

  1. W konsoli Google Cloud otwórz Menu  > Administracja > Konta usługi.

    Otwórz stronę Konta usługi

    Pozostałe kroki będą wykonywane w konsoli Google Cloud.

  2. Wybierz projekt Google Cloud.
  3. Kliknij Utwórz konto usługi.
  4. Wpisz nazwę konta usługi, która ma być wyświetlana w konsoli Google Cloud.
  5. Jeśli nie chcesz konfigurować kontroli dostępu już teraz, kliknij Gotowe, aby zakończyć tworzenie konta usługi. Aby skonfigurować kontrolę dostępu, kliknij Utwórz i kontynuuj, a potem przejdź do następnego kroku.
  6. Opcjonalnie: przypisz role do konta usługi, aby przyznać dostęp do zasobów projektu w chmurze Google Cloud oprócz zasobów Google Workspace. Więcej informacji znajdziesz w artykule Zarządzanie dostępem do projektów, folderów i organizacji.
  7. Kliknij Dalej.
  8. Opcjonalnie: wpisz użytkowników lub grupy, które mogą zarządzać tym kontem usługi i wykonywać na nim działania. Więcej informacji znajdziesz w artykule Przejmowanie tożsamości konta usługi.
  9. Aby zakończyć tworzenie konta usługi, 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 w chmurze Google Cloud oprócz zasobów Google Workspace. Więcej informacji znajdziesz w artykule Zarządzanie dostępem do projektów, folderów i organizacji.

Konto usługi pojawi się na stronie kont usługi. Następnie utwórz klucz prywatny dla konta usługi.

Tworzenie klucza prywatnego

Aby utworzyć i pobrać klucz prywatny dla konta usługi, wykonaj te czynności:

  1. W konsoli Google Cloud otwórz Menu  > Administracja i uprawnienia > Konta usługi.

    Otwórz stronę Konta usługi

    Pozostałe kroki będą wykonywane w konsoli Google Cloud.

  2. Wybierz projekt Google Cloud.
  3. Kliknij adres e-mail konta usługi, dla którego chcesz utworzyć klucz.
  4. Kliknij kartę Klucze.
  5. Kliknij menu Dodaj klucz i wybierz Utwórz nowy klucz.
  6. W polu Typ klucza wybierz JSON i kliknij Utwórz.

    Nowa para kluczy publicznych/prywatnych zostanie wygenerowana i pobrana na Twoje urządzenie jako plik klucza konta usługi. Zapisz pobrany plik JSON jako credentials.json w katalogu roboczym. Ten plik jest jedyną kopią tego klucza. Po pobraniu pliku klucza nie można go pobrać ponownie. Informacje o tym, jak bezpiecznie przechowywać klucz, znajdziesz w sprawdzonych metodach zarządzania kluczami konta usługi.

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

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

  1. W konsoli interfejsów API Google otwórz Menu  > Platforma uwierzytelniania Google > Branding.

    Przejdź do sekcji Elementy marki

  2. Jeśli platforma uwierzytelniania Google została już skonfigurowana, możesz skonfigurować te ustawienia ekranu zgody OAuth w sekcjach Branding, Odbiorcy i Dostęp do danych. Jeśli zobaczysz komunikat Platforma uwierzytelniania Google nie została jeszcze skonfigurowana, kliknij Rozpocznij:
    1. W sekcji 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ć, jeśli mają pytania dotyczące ich zgody.
    3. Kliknij Dalej.
    4. W sekcji Odbiorcy wybierz Wewnętrzny.
    5. Kliknij Dalej.
    6. W sekcji Informacje kontaktowe wpisz adres e-mail, na który będziesz otrzymywać powiadomienia o wszelkich zmianach w projekcie.
    7. Kliknij Dalej.
    8. W sekcji Finish (Zakończ) zapoznaj się z zasadami dotyczącymi danych użytkownika w usługach interfejsu API Google i jeśli je akceptujesz, kliknij I agree to the Google API Services: User Data Policy (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ę do użytku poza organizacją Google Workspace, musisz zmienić Typ użytkownika na Zewnętrzny. Następnie dodaj zakresy autoryzacji wymagane przez aplikację. Więcej informacji znajdziesz w pełnym przewodniku Konfigurowanie zgody OAuth.

Wdrażanie agenta AI ADK Travel Concierge

  1. Jeśli nie zostało to jeszcze zrobione, uwierzytelnij się za pomocą konta Google Cloud i skonfiguruj Google Cloud CLI do korzystania z Twojego projektu w chmurze.

    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 wyodrębnij 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 zasobnik Cloud Storage przeznaczony dla agenta AI ADK.

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

    Zastąp te elementy:

    1. CLOUD_STORAGE_BUCKET_NAME z unikalną nazwą zasobnika, której chcesz używać.
    2. PROJECT_ID z identyfikatorem utworzonego projektu Cloud.
    3. PROJECT_LOCATION z lokalizacją utworzonego projektu w chmurze.

  5. Ustaw te 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 te elementy:

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

  6. Zainstaluj i wdroż agenta AI ADK.

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

  7. Pobierz numer projektu i identyfikator silnika z ostatniego wydrukowanego logu jako PROJECT_NUMBER i ENGINE_ID. Będziesz ich potrzebować później do skonfigurowania projektu.

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

Przeglądanie przykładowego kodu

Opcjonalnie przed skonfigurowaniem projektu możesz zapoznać się z przykładowym kodem hostowanym w 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 wyodrębnij 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 pobrany w poprzednich krokach do katalogu projektu.

  4. W Konsoli interfejsów API Google 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 chmurze PROJECT_LOCATION.
    3. W sekcji URL punktu końcowego kliknij Ikona tworzenia kopii.
    4. Na liście Środowisko wykonawcze wybierz najnowszą wersję Pythona.
    5. W sekcji Uwierzytelnianie wybierz Zezwól na dostęp publiczny.
    6. W sekcji Kontenery, woluminy, sieć, zabezpieczenia w obszarze Zasoby:
      1. W polu Pamięć wybierz 1 GB.
      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óż źródło 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 te 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 numerem projektu agenta AI ADK Travel Concierge wdrożonego w poprzednich krokach.
    4. ENGINE_ID z identyfikatorem wyszukiwarki agenta AI ADK Travel Concierge wdrożonego w poprzednich krokach.
    5. BASE_URL z adresem URL punktu końcowego skopiowanym wcześniej.

Google Apps Script

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

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

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

  3. Nazwij kopię projektu Apps Script:

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

  4. W projekcie Apps Script kliknij Ikona ustawień projektu Edytor i przenieś plik VertexAi.gs nad plik AgentHandler.gs, korzystając z działania Przenieś plik wyżej.

  5. W projekcie Apps Script kliknij Ikona ustawień projektu Ustawienia projektu, Edytuj właściwości skryptu, a następnie Dodaj właściwość skryptu, aby dodać te właściwości skryptu:

  6. ENGINE_ID z identyfikatorem wyszukiwarki agenta AI ADK Travel ConciergeENGINE_ID wdrożonego w poprzednich krokach.

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

  8. PROJECT_NUMBER z numerem projektu agenta AI ADK Travel Concierge wdrożonego w poprzednich krokach, PROJECT_NUMBER.

  9. SERVICE_ACCOUNT_KEY z kluczem JSON z konta usługi pobranym w poprzednich krokach, np. { ... }.

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

  11. W projekcie Apps Script kliknij Ikona ustawień projektu Ustawienia projektu.

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

  13. W polu Numer projektu GCP wklej numer projektu agenta AI ADK Travel Concierge 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, Dokumentach, Arkuszach, Prezentacjach i na Dysku

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 z kodu źródłowego 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 do 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 (z wyjątkiem Google Chat), aby umożliwić testowanie.

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

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

Wdrażanie w Google Chat

Python

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

  1. W Konsoli interfejsów API wyszukajGoogle Chat API, kliknij Google Chat API, a następnie Zarządzaj i Konfiguracja.

    Otwórz stronę konfiguracji interfejsu Google Chat API

  2. Skonfiguruj aplikację 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 adres URL punktu końcowego BASE_URL.
    7. Zarejestruj szybkie polecenie, którego używa w pełni wdrożona aplikacja do obsługi 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 wybierz 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 kliknij Loguj błędy w usłudze Logging.
    10. Kliknij Zapisz.

Google Apps Script

Zainstaluj projekt Apps Script w Google Chat przy użyciu identyfikatora wdrożenia Head, aby umożliwić testowanie.

  1. W projekcie Apps Script kliknij Wdróż > Testuj wdrożenia, a następnie w sekcji Identyfikator wdrożenia głównego kliknij Ikona kopiowania identyfikatora wdrożenia z nagłówka Kopiuj.

  2. W Konsoli interfejsów API wyszukajGoogle Chat API, kliknij Google Chat API, a następnie Zarządzaj i Konfiguracja.

    Otwórz stronę konfiguracji interfejsu Google Chat API

  3. Skonfiguruj aplikację 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 wybierz Apps Script.
    5. W polu Identyfikator wdrożenia wklej skopiowany wcześniej Identyfikator wdrożenia głównego.
    6. Zarejestruj szybkie polecenie, którego używa w pełni wdrożona aplikacja do obsługi 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 wybierz 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 kliknij 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 nazwę aplikacji i wybierz ją Travel ADK AI Agent w wynikach wyszukiwania.
    3. W oknie dialogowym Install app kliknij Zainstaluj aplikację instalowaną.
    4. Okno dialogowe Install app zostanie zamknięte, a nowo utworzony pokój DM w Google Chat zostanie wybrany.

Aplikacja Google 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 agent AI na pasku bocznym.

  4. Aby zakoń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.

    Na pasku bocznym pojawi się odpowiedź agenta.

    Planowanie podróży w Gmailu

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

  7. Kliknij + > Zresetuj sesję.

    Otrzymasz nową wiadomość z potwierdzeniem zakończenia procesu: 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.

    Burza mózgów w Google Chat

  9. Wyślij wiadomość I want to go there! po przesłaniu zdjęcia dowolnego miejsca, np. wieży Eiffla.

    Otrzymasz nowe wiadomości z odpowiedzią agenta.

    Pobieranie szczegółów lokalizacji z załącznika do wiadomości na czacie

Ograniczenia

HTTP

W aplikacjach Google Workspace innych niż Chat agent AI ma te 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 upłynąć limit czasu: aktualizacje paska bocznego mogą przekroczyć limit czasu, jeśli ich ukończenie zajmie więcej niż kilka minut.

W Google Chat te ograniczenia nie występują.

Google Apps Script

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

  • Synchronizacja: odpowiedzi agenta AI są zwracane dopiero po pełnym zakończeniu (bez przesyłania strumieniowego).

  • Może upłynąć limit czasu: limit czasu prośby agenta AI upływa, gdy wykonanie działania zajmuje mu więcej niż minutę.

Dostosowywanie

To rozwiązanie obsługuje agentów AI ADK hostowanych w Vertex AI Agent Engine, podzbiór interfejsów aplikacji Google Workspace oraz renderowanie odpowiedzi specyficzne dla odpowiedzi przykładowego konsjerża podróży. 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 (moduły obsługi zdarzeń Google Workspace). Typowym rozszerzeniem byłoby włączenie dokumentów na Dysku jako funkcji kontekstowej aplikacji Dysk, podobnie jak w przypadku wiadomości Gmaila 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 to dodanie obsługi wielu sesji w przypadku oddzielnych rozmów użytkowników i innych platform do zarządzania agentami AI.

  • agent_handler.py: implementuje interfejsy specyficzne dla Vertex AI zdefiniowane w pliku vertex_ai.py w przypadku aplikacji do obsługi czatu i innych aplikacji. Typowym rozszerzeniem byłoby dodanie przycisków, za pomocą których użytkownicy mogliby przesyłać opinie o odpowiedziach agenta AI.

  • google_workspace.py: implementuje interakcje z platformą zarządzania agentami bez AI za pomocą wywołań interfejsu API. W tym przykładzie do zbierania szczegółów kontekstowych i podejmowania działań używane są tylko interfejsy API Google Workspace. Typowym rozszerzeniem byłoby dodanie funkcji pobierania firmowych baz danych 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 podwykonawców i aplikacji Workspace. Typowe rozszerzenia to dodanie obsługi nowych sposobów renderowania odpowiedzi w celu graficznego wyświetlania opcji lotów i innych agentów AI.

Google Apps Script

  • Code.gs: określa główne interfejsy i logikę interakcji użytkownika (moduły obsługi zdarzeń Google Workspace). Typowym rozszerzeniem byłoby włączenie dokumentów na Dysku jako funkcji kontekstowej dla aplikacji Dysk, podobnie jak 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 w przypadku oddzielnych rozmów użytkowników i innych platform do zarządzania agentami AI.

  • AgentHandler.gs: implementuje interfejsy specyficzne dla Vertex AI zdefiniowane w pliku VertexAi.gs w przypadku aplikacji do obsługi czatu i innych aplikacji. 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 kontekstowych i podejmowania działań używane są tylko interfejsy API Google Workspace. Typowym rozszerzeniem byłoby dodanie funkcji pobierania firmowych baz danych 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 w celu graficznego wyświetlania opcji lotów i innych agentów AI.

Czyszczenie danych

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

  1. W konsoli interfejsów API Google otwórz stronę Zarządzanie zasobami. Kliknij Menu > IAM i administrator > Zarządzaj zasobami.

    Otwórz Resource Manager

  2. Z listy projektów wybierz projekt do usunięcia, a potem kliknij Usuń .
  3. W oknie wpisz identyfikator projektu i kliknij Wyłącz, aby usunąć projekt.