Tworzenie aplikacji Google Chat z agentem Agent2UI

Na tej stronie dowiesz się, jak utworzyć dodatek do Google Workspace, który działa w Google Chat i współpracuje z agentem AI korzystającym z protokołu Agent2UI (A2UI). Agenta tworzysz za pomocą pakietu Agent Development Kit (ADK) i hostujesz go w Vertex AI Agent Engine.

Agenci AI autonomicznie postrzegają swoje otoczenie, wyciągają wnioski i wykonują złożone, wieloetapowe działania, aby osiągnąć określony cel. W tym samouczku wdrożysz podstawowego agenta AI, który zwraca statyczne informacje o profilu pobrane z narzędzia.

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

  • Agent A2UI odpowiada użytkownikowi wiadomością z tekstem i kartą zawierającą nazwę profilu, obraz i przycisk LinkedIn.
    Rysunek 1. Agent A2UI odpowiada użytkownikowi tekstem i kartą zawierającą imię i nazwisko, zdjęcie oraz przycisk LinkedIn.
  • Agent A2UI został zaktualizowany, aby zwracać również tytuł profilu.
    Rysunek 2. Agent A2UI został zaktualizowany, aby zwracać również tytuł profilu.
  • Agent A2UI odpowiada użytkownikowi wiadomością, w której na karcie wyświetla się nazwa profilu.
    Rysunek 3. Agent A2UI odpowiada użytkownikowi wiadomością, w której na karcie wyświetla się nazwa profilu.

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

Architektura aplikacji do obsługi czatu zaimplementowanej za pomocą agenta AI A2UI.

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 w Google Chat.
  2. Logika aplikacji do obsługi Google Chat, która jest 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 Chat generuje i wysyła adaptacyjne odpowiedzi asynchronicznie, używając Google Chat API do informowania o postępach agenta AI.
  6. Odpowiedzi są dostarczane do użytkownika.

Cele

  • skonfigurować środowisko,
  • Wdróż agenta A2UI.
  • wdrożyć 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, zapoznaj się z artykułem 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 Pythona.
  • Python Poetry: aby zainstalować to narzędzie, postępuj zgodnie z instrukcjami na oficjalnej stronie Poetry.
  • Google Cloud CLI: aby zainstalować interfejs, 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 w chmurze Google. W jednym projekcie Google Cloud możesz włączyć co najmniej 1 interfejs 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 było ją później opublikować.

  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 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 i 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:

Google Cloud Console

  1. W konsoli Google Cloud otwórz Menu  > Uprawnienia i 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ć mu dostęp do zasobów projektu 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ć mu dostęp do zasobów projektu 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.

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 > 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. Jest to jedyna kopia tego klucza. Po pobraniu pliku klucza nie można go pobrać ponownie. Informacje o tym, jak bezpiecznie przechowywać klucz, znajdziesz w artykule Sprawdzone metody zarządzania kluczami konta usługi.

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:

    Pobieranie 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 do obsługi Google Chat

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

    Otwórz projekt

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

  3. W projekcie Apps Script kliknij Ikona ustawień projektu Ustawienia projektu > Edytuj właściwości skryptu > Dodaj właściwość skryptu, aby dodać te 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 pobranym w poprzednich krokach, np. { ... }.

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

  5. W konsoli interfejsów API Google kliknij Menu  > Administracja > Ustawienia.

    Otwórz Ustawienia w obszarze Administracja

  6. Skopiuj wartość w polu Numer projektu.

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

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

  9. W sekcji 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 Ikona tworzenia kopii Kopiuj.
  3. Kliknij Gotowe.

Konfigurowanie aplikacji Google Chat

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

  1. W Konsoli interfejsów API 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 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  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 odkomentuj w narzędziu wiersz, który dodaje tytuł do zwracanych danych.

    apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py
    # 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 Google 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 zwróci błąd, w interfejsie Google Chat pojawi się komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć żądania”. Czasami interfejs Google Chat nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta Google Chat daje nieoczekiwany wynik, np. nie pojawia się wiadomość na karcie.

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 interfejsów API Google otwórz stronę Zarządzanie zasobami. Kliknij Menu > IAM i administrator > 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.