Tworzenie aplikacji Google Chat z agentem AI ADK

Na tej stronie dowiesz się, jak utworzyć dodatek do Google Workspace, który działa w Google Chat i współpracuje z agentem AI Agent Development Kit (ADK) hostowanym w Vertex AI Agent Engine.

Uwaga: w Google Chat dodatki są widoczne dla użytkowników jako aplikacje Google Chat. Aplikację do obsługi Google Chat możesz też utworzyć za pomocą wydarzeń interakcji interfejsu Google Chat API. Więcej informacji znajdziesz w artykule Rozszerzanie Google Chat – omówienie.

Agenci AI autonomicznie postrzegają swoje środowisko, rozumują i wykonują złożone, wieloetapowe działania, aby osiągnąć określony cel. Z tego samouczka dowiesz się, jak wdrożyć przykładową aplikację ADK LLM Auditor z wieloma agentami, która krytykuje i weryfikuje fakty za pomocą Gemini i groundingu z wyszukiwarką Google.

Ten diagram przedstawia architekturę i wzorzec przesyłania wiadomości:

Na powyższym diagramie użytkownik wchodzący w interakcję z aplikacją do czatowania zaimplementowaną za pomocą agenta AI ADK ma następujący przepływ informacji:

1. Użytkownik wysyła wiadomość do aplikacji w Google Chat w wiadomości bezpośredniej lub w pokoju czatu.
2. Logika aplikacji do obsługi Google Chat zaimplementowana w Apps Script lub jako serwer internetowy z punktami końcowymi HTTP odbiera i przetwarza wiadomość.
3. Agent AI zaimplementowany za pomocą ADK i hostowany w Vertex AI Agent Engine odbiera i przetwarza interakcję.
4. Opcjonalnie aplikacja Chat lub agent AI może być zintegrowana z usługami Google Workspace, takimi jak Kalendarz czy Arkusze, lub z innymi usługami Google, takimi jak Mapy Google czy YouTube.
5. Aplikacja Google Chat asynchronicznie wysyła odpowiedzi za pomocą interfejsu Google Chat API, aby informować o postępach agenta AI.
6. Odpowiedzi są dostarczane do użytkownika.

Cele

• skonfigurować środowisko,
• Wdróż agenta AI platformy ADK.
• Wdróż aplikację Google Chat.
• Skonfiguruj aplikację Google Chat.
• Przetestuj aplikację Google Chat.

Wymagania wstępne

• Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.
• Projekt Google Cloud z włączonymi płatnościami. Aby sprawdzić, czy w istniejącym projekcie włączone są płatności, przeczytaj artykuł Sprawdzanie stanu rozliczeń projektów. Aby utworzyć projekt i skonfigurować rozliczenia, przeczytaj artykuł Tworzenie projektu Google Cloud.

Konfigurowanie środowiska

Włączanie interfejsów Google Cloud API

Zanim zaczniesz korzystać z interfejsów API Google, musisz je włączyć w projekcie Google Cloud. W jednym projekcie Google Cloud możesz włączyć co najmniej 1 interfejs API.

• W konsoli Google Cloud włącz interfejsy Google Chat API, Vertex AI API i Cloud Resource Manager API.

  Włączanie interfejsów API

Konfigurowanie ekranu zgody OAuth

Wszystkie aplikacje korzystające z OAuth 2.0 wymagają konfiguracji ekranu akceptacji. Skonfigurowanie ekranu zgody OAuth aplikacji określa, co jest wyświetlane użytkownikom i osobom sprawdzającym aplikację, oraz rejestruje aplikację, aby można ją było później opublikować.

1. W konsoli Google Cloud przejdź do menu > Google Auth platform > Branding.

   Otwórz Elementy 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ć, jeśli mają pytania dotyczące ich zgody.
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 sekcji Zakończ zapoznaj się z zasadami dotyczącymi danych użytkownika w usługach interfejsu API Google, a jeśli je akceptujesz, kliknij 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.

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 swojego konta usługi, aby przyznać dostęp do zasobów swojego projektu Google Cloud. Aby uzyskać więcej informacji, zapoznaj się z sekcją Przyznawanie, zmienianie i cofanie 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 swojego konta usługi, aby przyznać dostęp do zasobów swojego 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.

Tworzenie klucza prywatnego

Ostrzeżenie: w tym przykładzie użyto wyeksportowanego klucza konta usługi, aby uprościć kod. Eksportowanie klucza prywatnego nie jest zalecane w środowisku produkcyjnym, ponieważ nie powinien on być przechowywany w niebezpiecznym miejscu, np. w systemie kontroli wersji.

Więcej informacji o bezpiecznych wdrożeniach kont usługi i sprawdzonych metodach znajdziesz w artykule Wybieranie sytuacji, w których warto używać kont usługi.

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

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

   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ługi znajdziesz w dokumentacji Uprawnień Google Cloud.

Wdrażanie agenta AI ADK

1. Otwórz przykładowy audytor LLM w Vertex AI Agent Garden:

   Otwórz próbkę

2. Kliknij Wdróż.

3. Jeśli pojawi się taka prośba, wybierz projekt Google Cloud.

4. Kliknij Wdróż w Cloud Shell.

5. Jeśli pojawi się monit, kliknij Autoryzuj i przejdź przez proces OAuth dla Cloud Shell.

6. Gdy Cloud Shell zostanie w pełni załadowany, naciśnij Enter, aby uruchomić wstępnie załadowany wiersz poleceń i rozpocząć wdrażanie.

7. Jeśli zostaniesz poproszony o podanie regionu, naciśnij Enter, aby użyć wartości domyślnej.

8. Po zakończeniu przejdź do Vertex AI Agent Engine:

   Otwórz silnik agenta Vertex AI

9. Kliknij , aby skopiować nazwę zasobu nowo wdrożonego agenta z tabeli.

Utwórz i skonfiguruj projekt aplikacji czatu

1. Kliknij poniższy przycisk, aby otworzyć projekt skryptu aplikacji ADK AI Agent Quickstart.

   Otwórz projekt

2. Kliknij Przegląd > Utwórz kopię.

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

   1. REASONING_ENGINE_RESOURCE_NAME z nazwą zasobu agenta Vertex AI skopiowaną w poprzednich krokach.
   2. SERVICE_ACCOUNT_KEY z kluczem JSON z konta usługi pobranego w poprzednich krokach, takich jak { ... }.

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

5. W konsoli Google Cloud przejdź do menu > Zarządzanie dostępem i administracja > Ustawienia.

   Otwórz Ustawienia w obszarze Administracja

6. W polu Numer projektu skopiuj wartość.

7. W projekcie Apps Script kliknij Ustawienia projektu.

8. W obszarze Projekt Google Cloud Platform (GCP) kliknij opcję Zmień projekt.

9. W polu Numer projektu GCP wklej numer projektu Google Cloud skopiowany w poprzednich krokach.

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

Tworzenie wdrożenia testowego

Do tego projektu Apps Script potrzebny jest identyfikator wdrożenia, aby można go było użyć w następnym kroku.

Aby uzyskać identyfikator wdrożenia głównego, wykonaj te czynności:

1. W projekcie Apps Script aplikacji do Google Chat kliknij Wdróż > Wdrożenia testowe.
2. W sekcji Identyfikator wdrożenia głównego kliknij Kopiuj.
3. Kliknij Gotowe.

Konfigurowanie aplikacji Google Chat

Aby wdrożyć aplikację Google Chat do testowania, wykonaj te czynności:

1. W konsoli wyszukaj Google Chat API i kliknij Google Chat API.
2. Kliknij Zarządzaj.

3. Kliknij Konfiguracja i skonfiguruj aplikację Chat:

   1. W polu Nazwa aplikacji wpisz ADK Quickstart.
   2. W polu Avatar URL (Adres URL awatara) wpisz https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
   3. W polu Opis wpisz ADK Quickstart.
   4. W sekcji Funkcje wybierz Dołączanie do pokoi i rozmów grupowych.
   5. W sekcji Ustawienia połączenia wybierz Projekt Apps Script.
   6. W polu Identyfikator wdrożenia wklej skopiowany wcześniej identyfikator wdrożenia głównego.
   7. W sekcji Widoczność kliknij Określeni użytkownicy i grupy w Twojej domenie i wpisz swój adres e-mail.

4. Kliknij Zapisz.

Aplikacja Chat jest gotowa do odpowiadania na wiadomości.

Testowanie aplikacji Google Chat

Aby przetestować aplikację do Google Chat, otwórz czat z aplikacją i wyślij wiadomość:

1. Otwórz Google Chat, korzystając z konta Google Workspace, które zostało podane podczas dodawania siebie jako zaufanego testera.

   Otwórz Google Chat

2. Kliknij  Nowy czat.
3. W polu Dodaj co najmniej 1 osobę wpisz nazwę aplikacji Chat.

4. Wybierz aplikację Chat z wyników. Otworzy się czat.

   Uwaga: jeśli nie widzisz swojej aplikacji do obsługi czatu na liście wyników, sprawdź, czy Twoje konto Google Workspace zostało uwzględnione w ustawieniach Widoczność na stronie Konfiguracja interfejsu Chat API w Google Cloud Console.

5. Na nowym czacie z aplikacją wpisz The Eiffel Tower was completed in 1900 i naciśnij enter.

   Aplikacja Chat odpowie za pomocą odpowiedzi podagentów Krytyk i Korektor.

Aby dodać zaufanych testerów i dowiedzieć się więcej o testowaniu funkcji interaktywnych, przeczytaj artykuł Testowanie funkcji interaktywnych w aplikacjach Google Chat.

Rozwiązywanie problemów

Gdy aplikacja Google Chat lub karta zwraca błąd, interfejs Google Chat wyświetla komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć Twojej prośby”. Czasami interfejs Google Chat nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta Google Chat daje nieoczekiwany wynik, np. wiadomość na karcie może się nie pojawić.

Chociaż w interfejsie czatu może nie wyświetlać się komunikat o błędzie, opisowe komunikaty o błędach i dane logowania są dostępne, aby pomóc w naprawieniu błędów, gdy rejestrowanie błędów w aplikacjach na czat jest włączone. Pomoc dotyczącą wyświetlania, debugowania i naprawiania błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat.

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 wpisz identyfikator projektu i kliknij Wyłącz, aby usunąć projekt.

Powiązane artykuły

• Tworzenie aplikacji Google Chat z agentem AI ADK udostępnianym przez A2A
• Tworzenie aplikacji Google Chat z agentem AI ADK udostępnianym przez A2UI
• Sprawdzanie faktów za pomocą agenta AI ADK i modelu Gemini
• Planowanie podróży z pomocą agenta AI dostępnego w różnych usługach Google Workspace
• Integrowanie podstawowych koncepcji AI w aplikacjach Google Chat
• Odpowiadanie na pytania na podstawie rozmów w Google Chat za pomocą aplikacji Gemini AI Chat
• Reagowanie na incydenty za pomocą Google Chat, Vertex AI, Apps Script i uwierzytelniania użytkowników
• Zarządzanie projektami za pomocą Google Chat, Vertex AI i Firestore