Tworzenie aplikacji Google Chat z agentem Agent2UI

Na tej stronie wyjaśniono, jak utworzyć dodatek do Google Workspace, który będzie działał w Google Chat i będzie współpracował z agentem AI korzystającym z protokołu Agent2UI (A2UI). Możesz opracować agenta za pomocą pakietu narzędzi programistycznych Agent Development Kit (ADK) i hostować go w Vertex AI Agent Engine.

Agenci AI autonomicznie postrzegają swoje otoczenie, rozumują i wykonują złożone, wieloetapowe działania w celu osiągnięcia określonego celu. W tym samouczku wdrożysz podstawowego agenta AI, który zwraca statyczne informacje o profilu pobrane z narzędzia.

Technologia A2UI umożliwia agentom AI generowanie adaptacyjnych, rozbudowanych i interaktywnych interfejsów użytkownika, które są renderowane natywnie. Możesz wtedy skupić się na logice agentów AI, a nie na interfejsach użytkownika.

Poniższy diagram przedstawia architekturę i wzorzec przesyłania komunikatów:

Na diagramie przedstawiono przepływ informacji podczas interakcji użytkownika z aplikacją do czatu zaimplementowaną za pomocą agenta A2UI:

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 A2UI 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 generuje i wysyła adaptacyjne odpowiedzi asynchronicznie, korzystając z Google Chat API do przekazywania informacji o postępach agenta AI.
6. Odpowiedzi są dostarczane do użytkownika.

Cele

• skonfigurować środowisko,
• Wdróż agenta A2UI.
• 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.
• Python 3.11 lub nowszy: aby zainstalować Pythona, postępuj zgodnie z instrukcjami na oficjalnej stronie internetowej Pythona.
• Python Poetry: aby zainstalować to narzędzie, postępuj zgodnie z instrukcjami na oficjalnej stronie Poetry.
• Interfejs wiersza poleceń Google Cloud: aby go zainstalować, postępuj zgodnie z instrukcjami na oficjalnej stronie 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 protokołu OAuth 2.0 wymagają konfiguracji ekranu zgody. Skonfigurowanie ekranu zgody OAuth w aplikacji definiuje informacje wyświetlane użytkownikom i recenzentom aplikacji, a także rejestruje aplikację, aby można ją było później opublikować.

1. W konsoli Google Cloud przejdź do menu 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ę 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.

Tworzenie konta usługi w konsoli Google Cloud

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

Konsola Google Cloud

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

   Otwórz stronę Konta usługi

2. Kliknij Utwórz konto usługi.
3. Wpisz szczegóły konta usługi i kliknij Utwórz i kontynuuj.
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: 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 Zarządzanie przejmowaniem tożsamości konta 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. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie uprawnień dostępu do zasobów.

Konto usługi pojawi się na stronie kont 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 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 A2UI

1. Jeśli jeszcze tego nie zrobiono, uwierzytelnij się na koncie Google Cloud i skonfiguruj Google Cloud CLI do korzystania 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 projektu w Cloud.

2. Pobierz repozytorium GitHub googleworkspace/add-ons-samples za pomocą tego przycisku:

   Pobierz repozytorium

3. W wybranym lokalnym środowisku programistycznym wyodrębnij pobrany plik archiwum i otwórz katalog add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui.

   unzip add-ons-samples-main.zip
   cd add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui

4. Utwórz nowy zasobnik Cloud Storage przeznaczony dla agenta ADK.

   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ą zasobnika, której chcesz użyć.
   2. PROJECT_ID identyfikatorem Twojego projektu Cloud;
   3. PROJECT_LOCATION z lokalizacją projektu Cloud.

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

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   Zastąp następujące elementy:

   1. CLOUD_STORAGE_BUCKET_NAME nazwą utworzonego zasobnika.
   2. PROJECT_ID identyfikatorem Twojego projektu Cloud;
   3. PROJECT_LOCATION z lokalizacją projektu Cloud.

6. Zainstaluj i wdroż agenta ADK ze środowiska wirtualnego.

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

7. Pobierz identyfikator agenta. Będzie on potrzebny później podczas konfigurowania aplikacji Chat.

   python3 deployment/deploy.py --list

Tworzenie i konfigurowanie projektu aplikacji w Google Chat

1. Kliknij ten przycisk, aby otworzyć projekt A2UI AI Agent Quickstart Apps Script.

   Otwórz projekt

2. Kliknij info_outline 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 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 Cloud i projekt Apps Script są teraz połączone.

Utwórz wdrożenie testowe

Potrzebujesz identyfikatora wdrożenia dla tego projektu Apps Script, aby móc go użyć w następnym kroku.

Aby uzyskać identyfikator rozmieszczenia głowicy, wykonaj następujące czynności:

1. W projekcie Apps Script aplikacji Chat kliknij Wdróż > Testuj wdrożenia.
2. Pod Identyfikator wdrożenia głowicy, kliknij Kopia.
3. Kliknij Gotowe.

Skonfiguruj aplikację Czat

Aby wdrożyć aplikację Google Chat w celu testowania, wykonaj poniższe kroki przy użyciu wdrożenia Apps Script:

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

3. Kliknij Konfiguracja i skonfiguruj aplikację Chat:

   1. W polu Nazwa aplikacji wpisz A2UI 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 A2UI 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 add Nowy czat.
3. W polu Dodaj co najmniej 1 osobę wpisz nazwę aplikacji Chat.

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

5. Na nowym czacie z aplikacją wpisz Hello! i naciśnij enter.

   Aplikacja do obsługi czatu odpowiada wiadomością z tekstem powitania i kartą zawierającą nazwę profilu, obraz i przycisk LinkedIn.

6. Zaktualizuj implementację agenta A2UI, aby zaczął zwracać również tytuł profilu.

   W lokalnym środowisku deweloperskim otwórz plik a2ui/agent.py i usuń komentarz z wiersza w narzędziu, który dodaje tytuł do zwracanych danych.

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

   Wyświetl w GitHubie
   # Copyright 2026 Google LLC
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #     http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   
   """A2UI agent."""
   
   from google.adk.agents import LlmAgent
   from google.adk.tools.tool_context import ToolContext
   import json
   
   # The schema for any A2UI message. This never changes.
   from .a2ui_schema import A2UI_SCHEMA
   
   def get_user_profile(tool_context: ToolContext) -> str:
       """Call this tool to get the current user profile."""
       return json.dumps({
           "name": "Pierrick Voulet",
           # "title": "DevRel Engineer @ Google Workspace | Gen AI & AI Agents & Agentic AI | Automation & Digital Transformation",
           "imageUrl": "https://io.google/2024/speakers/3ea87822-3160-4d54-89dd-57e185085f79_240.webp",
           "linkedin": "https://www.linkedin.com/in/pierrick-voulet/"
       })
   
   AGENT_INSTRUCTION="""
   You are a user profile assistant. Your goal is to help users get their profile information using a rich UI.
   
   To achieve this, you MUST follow these steps to answer user requests:
   
   1.  You MUST call the `get_user_profile` tool and extract all the user profile information from the result.
   2.  You MUST generate a final a2ui UI JSON based on the user profile information extracted in the previous step."""
   
   A2UI_AND_AGENT_INSTRUCTION = AGENT_INSTRUCTION + f"""
   
   To generate a valid a2ui UI JSON, you MUST follow these rules:
   1.  Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`.
   2.  The first part is your conversational text response.
   3.  The second part is a single, raw JSON object which is a list of A2UI messages.
   4.  The JSON part MUST validate against the A2UI JSON SCHEMA provided below.
   
   To represent the user profile, you MUST use the following A2UI message types:
   1.  Buttons MUST be used to represent links (e.g., LinkedIn profile link).
   2.  Image MUST be used to represent the user's profile picture.
   
   ---BEGIN A2UI JSON SCHEMA---
   {A2UI_SCHEMA}
   ---END A2UI JSON SCHEMA---
   """
   
   root_agent = LlmAgent(
       name="user_profile",
       model="gemini-2.5-flash",
       instruction=A2UI_AND_AGENT_INSTRUCTION,
       description="An agent that returns the current user profile.",
       tools=[get_user_profile]
   )

7. Zaktualizuj wcześniej wdrożony pakiet ADK do nowej wersji implementacji.

   python3 deployment/deploy.py --update --resource_id=RESOURCE_ID

   Zastąp RESOURCE_ID nazwą zasobu agenta Vertex AI skopiowaną w poprzednich krokach.

8. Na czacie z aplikacją wpisz Hello again! i naciśnij enter.

   Aplikacja Chat odpowiada wiadomością zawierającą tekst i kartę z tytułem profilu.

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.

1. W konsoli Google Cloud otwórz stronę Zarządzanie zasobami. Kliknij Menu 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ń delete.
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
• Tworzenie aplikacji Google Chat z agentem A2A
• 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