Tworzenie aplikacji Google Chat z agentem Agent2Agent

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 Agent2Agent (A2A). Agenta tworzysz za pomocą pakietu Agent Development Kit (ADK) i hostujesz go w Vertex AI Agent Engine.

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ę LLM Auditor z wieloma agentami, która krytykuje i weryfikuje fakty za pomocą Gemini i groundingu w wyszukiwarce Google.

Przykładowa aplikacja wieloagentowa LLM Auditor jako aplikacja do obsługi czatu.

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

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

Na diagramie użytkownik wchodzący w interakcję z aplikacją do czatu zaimplementowaną za pomocą agenta A2A 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 A2A 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 wysyła odpowiedzi asynchronicznie, korzystając z interfejsu Google Chat API, aby informować o postępach agenta AI.
  6. Odpowiedzi są dostarczane do użytkownika.

Cele

  • skonfigurować środowisko,
  • Wdróż agenta A2A.
  • wdrożyć aplikację Google Chat;
  • Skonfiguruj aplikację Google Chat.
  • Przetestuj aplikację Google Chat.

Wymagania wstępne

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.

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 otwórz Menu  > Google Auth platform > Branding.

    Otwórz Elementy marki

  2. Jeśli masz już skonfigurowany Google Auth platform, możesz skonfigurować te ustawienia ekranu zgody OAuth w sekcjach Branding, Odbiorcy i Dostęp do danych. Jeśli zobaczysz komunikat Google Auth platform Jeszcze nie skonfigurowano, 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 wszelkich 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  > Administracja > Konta usługi.

    Otwórz stronę Konta usługi

  2. Kliknij Utwórz konto usługi.
  3. Wpisz szczegóły konta usługi, a następnie 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  > 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 A2A

  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 z przykładami ADK, klikając ten przycisk:

    Pobierz adk-samples

  3. W wybranym lokalnym środowisku programistycznym wyodrębnij pobrany plik archiwum i otwórz katalog adk-samples/python/agents/llm-auditor.

    unzip adk-samples-main.zip
cd adk-samples-main/python/agents/llm-auditor

  4. Zaktualizuj implementację, aby wdrożyć agenta ADK jako zdalnego agenta A2A:

    1. pyproject.toml dodaj zależności od pakietów SDK ADK i A2A w grupie wdrożenia.

      apps-script/chat/a2a-ai-agent/llm-auditor/pyproject.toml
      [project]
name = "llm-auditor"
version = "0.1.0"
description = "The LLM Auditor evaluates LLM-generated answers, verifies actual accuracy using the web, and refines the response to ensure alignment with real-world knowledge."
authors = [
    { name = "Chun-Sung Ferng", email = "csferng@google.com" },
    { name = "Cyrus Rashtchian", email = "cyroid@google.com" },
    { name = "Da-Cheng Juan", email = "dacheng@google.com" },
    { name = "Ivan Kuznetsov", email = "ivanku@google.com" },
]
license = "Apache License 2.0"
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.10"
google-adk = "^1.0.0"
google-cloud-aiplatform = { extras = [
    "adk",
    "agent-engines",
], version = "^1.93.0" }
google-genai = "^1.9.0"
pydantic = "^2.10.6"
python-dotenv = "^1.0.1"

[tool.poetry.group.dev]
optional = true

[tool.poetry.group.dev.dependencies]
google-adk = { version = "^1.0.0", extras = ["eval"] }
pytest = "^8.3.5"
pytest-asyncio = "^0.26.0"

[tool.poetry.group.deployment]
optional = true

[tool.poetry.group.deployment.dependencies]
absl-py = "^2.2.1"
google-adk = "^1.0.0"
a2a-sdk = "^0.3.0"

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

    2. deployment/deploy.py: zastąp wdrożenie aplikacji ADK wdrożeniem agenta i karty A2A.

      apps-script/chat/a2a-ai-agent/llm-auditor/deployment/deploy.py
      # Copyright 2025 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.

"""Deployment script for LLM Auditor."""

import os

from absl import app
from absl import flags
from dotenv import load_dotenv
from llm_auditor.agent import root_agent
import vertexai
from vertexai import agent_engines

# A2A wrapping
from a2a.types import AgentSkill
from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
from google.adk.runners import InMemoryRunner
from vertexai.preview.reasoning_engines.templates.a2a import create_agent_card
from vertexai.preview.reasoning_engines import A2aAgent

FLAGS = flags.FLAGS
flags.DEFINE_string("project_id", None, "GCP project ID.")
flags.DEFINE_string("location", None, "GCP location.")
flags.DEFINE_string("bucket", None, "GCP bucket.")
flags.DEFINE_string("resource_id", None, "ReasoningEngine resource ID.")

flags.DEFINE_bool("list", False, "List all agents.")
flags.DEFINE_bool("create", False, "Creates a new agent.")
flags.DEFINE_bool("delete", False, "Deletes an existing agent.")
flags.mark_bool_flags_as_mutual_exclusive(["create", "delete"])


def create() -> None:
    """Creates an agent engine for LLM Auditor."""
    agent_card = create_agent_card(
        agent_name=root_agent.name,
        description=root_agent.description,
        skills=[AgentSkill(
            id='audit_llm_output',
            name='Audit LLM Output',
            description='Critiques and revises outputs from large language models.',
            tags=['LLM', 'Audit', 'Revision'],
            examples=[
                'The earth is flat.',
                'The capital of France is Berlin.',
                'The last winner of the Super Bowl was the New England Patriots in 2020.',
            ],
        )]
    )
    a2a_agent = A2aAgent(
        agent_card=agent_card,
        agent_executor_builder=lambda: A2aAgentExecutor(
            runner=InMemoryRunner(
                app_name=root_agent.name,
                agent=root_agent,
            )
        )
    )
    a2a_agent.set_up()

    remote_agent = agent_engines.create(
        a2a_agent,
        display_name=root_agent.name,
        requirements=[
                "google-adk (>=0.0.2)",
                "google-cloud-aiplatform[agent_engines] (>=1.88.0,<2.0.0)",
                "google-genai (>=1.5.0,<2.0.0)",
                "pydantic (>=2.10.6,<3.0.0)",
                "absl-py (>=2.2.1,<3.0.0)",
                "a2a-sdk>=0.3.22",
                "uvicorn",
        ],
        # In-memory runner
        max_instances=1,
        env_vars ={
            "NUM_WORKERS": "1"
        },
        extra_packages=["./llm_auditor"],
    )
    print(f"Created remote agent: {remote_agent.resource_name}")


def delete(resource_id: str) -> None:
    remote_agent = agent_engines.get(resource_id)
    remote_agent.delete(force=True)
    print(f"Deleted remote agent: {resource_id}")


def list_agents() -> None:
    remote_agents = agent_engines.list()
    TEMPLATE = '''
{agent.name} ("{agent.display_name}")
- Create time: {agent.create_time}
- Update time: {agent.update_time}
'''
    remote_agents_string = '\n'.join(TEMPLATE.format(agent=agent) for agent in remote_agents)
    print(f"All remote agents:\n{remote_agents_string}")

def main(argv: list[str]) -> None:
    del argv  # unused
    load_dotenv()

    project_id = (
        FLAGS.project_id
        if FLAGS.project_id
        else os.getenv("GOOGLE_CLOUD_PROJECT")
    )
    location = (
        FLAGS.location if FLAGS.location else os.getenv("GOOGLE_CLOUD_LOCATION")
    )
    bucket = (
        FLAGS.bucket if FLAGS.bucket
        else os.getenv("GOOGLE_CLOUD_STORAGE_BUCKET")
    )

    print(f"PROJECT: {project_id}")
    print(f"LOCATION: {location}")
    print(f"BUCKET: {bucket}")

    if not project_id:
        print("Missing required environment variable: GOOGLE_CLOUD_PROJECT")
        return
    elif not location:
        print("Missing required environment variable: GOOGLE_CLOUD_LOCATION")
        return
    elif not bucket:
        print(
            "Missing required environment variable: GOOGLE_CLOUD_STORAGE_BUCKET"
        )
        return

    vertexai.init(
        project=project_id,
        location=location,
        staging_bucket=f"gs://{bucket}",
    )

    if FLAGS.list:
        list_agents()
    elif FLAGS.create:
        create()
    elif FLAGS.delete:
        if not FLAGS.resource_id:
            print("resource_id is required for delete")
            return
        delete(FLAGS.resource_id)
    else:
        print("Unknown command")


if __name__ == "__main__":
    app.run(main)

  5. 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.

  6. 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.

  7. 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

  8. 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 A2A 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 Google Cloud otwórz Menu  > Administracja > Ustawienia.

    Otwórz Ustawienia w obszarze Administracja

  6. W polu Numer projektu skopiuj wartość.

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

  8. W sekcji Projekt Google Cloud Platform (GCP) kliknij 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óż > Testuj wdrożenia.
  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 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 A2A 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 A2A 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 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, w interfejsie Google Chat pojawia się 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 > 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.