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 komunikuje się 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ą groundingu w Gemini i 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 typu 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.
  • Wdróż 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 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 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  > 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:

    Pobieranie przykładów 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 agentem i kartą 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 w 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 kolejno 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. Zastąp REASONING_ENGINE_RESOURCE_NAME 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óż > 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 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, 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 > 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.