Créer une application Google Chat avec un agent Agent2Agent

Cette page explique comment créer un module complémentaire Google Workspace qui fonctionne dans Google Chat et qui interagit avec un agent d'IA utilisant le protocole Agent2Agent (A2A). Vous développez l'agent à l'aide de l'Agent Development Kit (ADK) et l'hébergez dans Vertex AI Agent Engine.

Les agents IA perçoivent leur environnement de manière autonome, raisonnent et exécutent des actions complexes en plusieurs étapes pour atteindre un objectif défini. Dans ce tutoriel, vous allez déployer l'exemple multi-agent LLM Auditor qui critique et révise les faits à l'aide de l'ancrage Gemini et de la recherche Google.

Exemple multi-agents de l'auditeur LLM en tant qu'application Chat.

Le diagramme suivant illustre l'architecture et le modèle de messagerie :

Architecture d'une application de chat implémentée avec un agent d'IA A2A.

Dans le diagramme, un utilisateur qui interagit avec une application de chat implémentée avec un agent A2A suit le flux d'informations suivant :

  1. Un utilisateur envoie un message à une application Chat, en passant par un message privé ou un espace Chat.
  2. La logique de l'application Chat, implémentée dans Apps Script ou en tant que serveur Web avec des points de terminaison HTTP, reçoit et traite le message.
  3. L'agent A2A hébergé avec Vertex AI Agent Engine reçoit et traite l'interaction.
  4. L'application Chat ou l'agent d'IA peuvent éventuellement s'intégrer aux services Google Workspace, tels que Google Agenda ou Google Sheets, ou à d'autres services Google, tels que Google Maps ou YouTube.
  5. L'application Chat envoie des réponses de manière asynchrone, en utilisant l'API Google Chat pour communiquer la progression de l'agent d'IA.
  6. Les réponses sont envoyées à l'utilisateur.

Objectifs

  • configurer votre environnement ;
  • Déployez l'agent A2A.
  • Déployez l'application Chat.
  • Configurez l'application Chat.
  • Testez l'application Chat.

Prérequis

Configurer votre environnement

Activer les API Google Cloud

Avant d'utiliser les API Google, vous devez les activer dans un projet Google Cloud. Vous pouvez activer une ou plusieurs API dans un même projet Google Cloud.

  • Dans la console Google Cloud, activez les API Google Chat, Vertex AI et Cloud Resource Manager.

    Activer les API

Configurer l'écran d'autorisation OAuth

Toutes les applications utilisant OAuth 2.0 nécessitent une configuration de l'écran de consentement. La configuration de l'écran de consentement OAuth de votre application définit ce qui est affiché aux utilisateurs et aux évaluateurs de l'application, et enregistre votre application pour que vous puissiez la publier ultérieurement.

  1. Dans la console Google Cloud, accédez à Menu  > Google Auth platform > Branding.

    Accéder à la page "Branding"

  2. Si vous avez déjà configuré Google Auth platform, vous pouvez configurer les paramètres de l'écran de consentement OAuth suivants dans Branding, Audience et Accès aux données. Si le message Google Auth platform pas encore configuré s'affiche, cliquez sur Premiers pas :
    1. Sous Informations sur l'application, dans Nom de l'application, saisissez le nom de l'application.
    2. Dans Adresse e-mail d'assistance utilisateur, sélectionnez une adresse e-mail d'assistance que les utilisateurs pourront contacter s'ils ont des questions sur leur consentement.
    3. Cliquez sur Suivant.
    4. Sous Audience, sélectionnez Interne.
    5. Cliquez sur Suivant.
    6. Sous Coordonnées, saisissez une adresse e-mail à laquelle vous recevrez des notifications en cas de modification de votre projet.
    7. Cliquez sur Suivant.
    8. Sous Terminer, consultez le Règlement sur les données utilisateur dans les services d'API Google et, si vous l'acceptez, sélectionnez J'accepte le Règlement sur les données utilisateur dans les services d'API Google.
    9. Cliquez sur Continuer.
    10. Cliquez sur Créer.
  3. Pour l'instant, vous pouvez ignorer l'ajout de niveaux d'accès. À l'avenir, lorsque vous créerez une application à utiliser en dehors de votre organisation Google Workspace, vous devrez définir le type d'utilisateur sur Externe. Ajoutez ensuite les niveaux d'autorisation dont votre application a besoin. Pour en savoir plus, consultez le guide complet Configurer l'écran de consentement OAuth.

Créer un compte de service dans la console Google Cloud

Créez un compte de service avec le rôle Vertex AI User en procédant comme suit :

Console Google Cloud

  1. Dans la console Google Cloud, accédez au menu  > IAM et administration > Comptes de service.

    Accéder à la page "Comptes de service"

  2. Cliquez sur Créer un compte de service.
  3. Renseignez les informations du compte de service, puis cliquez sur Créer et continuer.
  4. Facultatif : Attribuez des rôles à votre compte de service pour lui accorder l'accès aux ressources de votre projet Google Cloud. Pour en savoir plus, consultez Accorder, modifier et révoquer les accès à des ressources.
  5. Cliquez sur Continuer.
  6. Facultatif : Saisissez les utilisateurs ou les groupes qui peuvent gérer ce compte de service et effectuer des actions avec. Pour en savoir plus, consultez Gérer l'emprunt d'identité d'un compte de service.
  7. Cliquez sur OK. Notez l'adresse e-mail du compte de service.

CLI gcloud

  1. Créez le compte de service : 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. Facultatif : Attribuez des rôles à votre compte de service pour lui accorder l'accès aux ressources de votre projet Google Cloud. Pour en savoir plus, consultez Accorder, modifier et révoquer les accès à des ressources.

Le compte de service s'affiche sur la page "Comptes de service".

Créer une clé privée

Pour créer et télécharger une clé privée pour le compte de service, procédez comme suit :

  1. Dans la console Google Cloud, accédez au menu  > IAM et administration > Comptes de service.

    Accéder à la page "Comptes de service"

  2. Sélectionnez votre compte de service.
  3. Cliquez sur Clés > Ajouter une clé > Créer une clé.
  4. Sélectionnez JSON, puis cliquez sur Créer.

    La nouvelle paire de clés publique/privée est générée et téléchargée sur votre ordinateur sous la forme d'un nouveau fichier. Enregistrez le fichier JSON téléchargé sous le nom credentials.json dans votre répertoire de travail. Ce fichier est la seule copie de cette clé. Pour savoir comment stocker votre clé de manière sécurisée, consultez Gérer les clés de compte de service.

  5. Cliquez sur Fermer.

Pour en savoir plus sur les comptes de service, consultez la section Comptes de service dans la documentation Google Cloud IAM.

Déployer l'agent A2A

  1. Si vous ne l'avez pas déjà fait, authentifiez-vous avec votre compte Google Cloud et configurez Google Cloud CLI pour utiliser votre projet Google Cloud.

    gcloud auth application-default login
gcloud config set project PROJECT_ID
gcloud auth application-default set-quota-project PROJECT_ID

    Remplacez PROJECT_ID par l'ID de votre projet Cloud.

  2. Téléchargez le dépôt GitHub des exemples ADK à l'aide de ce bouton :

    Télécharger adk-samples

  3. Dans l'environnement de développement local de votre choix, extrayez le fichier d'archive téléchargé et ouvrez le répertoire adk-samples/python/agents/llm-auditor.

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

  4. Mettez à jour l'implémentation pour déployer l'agent ADK en tant qu'agent A2A distant :

    1. pyproject.toml : ajoutez les dépendances ADK et A2A SDK dans le groupe de déploiement.

      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 : remplacez le déploiement de l'application ADK par un agent et une carte 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. Créez un bucket Cloud Storage dédié à l'agent ADK.

    gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

    Remplacez les éléments suivants :

    1. CLOUD_STORAGE_BUCKET_NAME par un nom de bucket unique que vous souhaitez utiliser.
    2. PROJECT_ID par l'ID de votre projet Cloud.
    3. PROJECT_LOCATION par l'emplacement de votre projet Cloud.

  6. Définissez les variables d'environnement suivantes :

    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

    Remplacez les éléments suivants :

    1. CLOUD_STORAGE_BUCKET_NAME par le nom du bucket que vous avez créé.
    2. PROJECT_ID par l'ID de votre projet Cloud.
    3. PROJECT_LOCATION par l'emplacement de votre projet Cloud.

  7. Installez et déployez l'agent ADK à partir de l'environnement virtuel.

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

  8. Récupérez l'ID de l'agent. Vous en aurez besoin plus tard, lorsque vous configurerez l'application Chat.

    python3 deployment/deploy.py --list

Créer et configurer le projet d'application Chat

  1. Cliquez sur le bouton suivant pour ouvrir le projet Apps Script Démarrage rapide de l'agent d'IA A2A.

    Ouvrir le projet

  2. Cliquez sur Présentation > Icône permettant de créer une copie Créer une copie.

  3. Dans votre projet Apps Script, cliquez sur Icône des paramètres du projet Paramètres du projet > Modifier les propriétés du script > Ajouter une propriété de script pour ajouter les propriétés de script suivantes :

    1. REASONING_ENGINE_RESOURCE_NAME par le nom de ressource de l'agent Vertex AI copié lors des étapes précédentes.
    2. SERVICE_ACCOUNT_KEY avec la clé JSON du compte de service téléchargée lors des étapes précédentes, par exemple { ... }.

  4. Cliquez sur Enregistrer les propriétés du script.

  5. Dans la console Google Cloud, accédez à Menu  > IAM et administration > Paramètres.

    Accéder à la page Paramètres de la section IAM et administration

  6. Dans le champ Numéro du projet, copiez la valeur.

  7. Dans votre projet Apps Script, cliquez sur Icône des paramètres du projet Paramètres du projet.

  8. Sous Projet Google Cloud Platform (GCP), cliquez sur Changer de projet.

  9. Dans Numéro de projet GCP, collez le numéro de projet Google Cloud copié lors des étapes précédentes.

  10. Cliquez sur Définir un projet. Le projet Cloud et le projet Apps Script sont désormais associés.

Créer un déploiement de test

Vous avez besoin d'un ID de déploiement pour ce projet Apps Script afin de pouvoir l'utiliser à l'étape suivante.

Pour obtenir l'ID de déploiement principal :

  1. Dans le projet Apps Script de l'application Chat, cliquez sur Déployer > Tester les déploiements.
  2. Sous ID du déploiement "Head", cliquez sur Icône permettant de créer une copie Copier.
  3. Cliquez sur OK.

Configurer l'application Chat

À l'aide de votre déploiement Apps Script, suivez ces étapes pour déployer l'application Google Chat à des fins de test :

  1. Dans la console, recherchez Google Chat API, puis cliquez sur API Google Chat.
  2. Cliquez sur Gérer.

  3. Cliquez sur Configuration et configurez l'application Chat :

    1. Dans le champ Nom de l'application, saisissez A2A Quickstart.
    2. Dans le champ URL de l'avatar, saisissez https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
    3. Dans le champ Description, saisissez A2A Quickstart.
    4. Sous Fonctionnalité, sélectionnez Rejoindre des espaces et des conversations de groupe.
    5. Sous "Paramètres de connexion", sélectionnez Projet Apps Script.
    6. Dans le champ Deployment ID (ID de déploiement), collez l'ID de déploiement Head que vous avez copié précédemment.
    7. Sous "Visibilité", sélectionnez Utilisateurs et groupes spécifiques de votre domaine, puis saisissez votre adresse e-mail.

  4. Cliquez sur Enregistrer.

L'application Chat est prête à répondre aux messages.

Tester l'application Chat

Pour tester votre application Chat, ouvrez un espace de message privé avec l'application Chat et envoyez un message :

  1. Ouvrez Google Chat avec le compte Google Workspace que vous avez fourni lorsque vous vous êtes ajouté en tant que testeur de confiance.

    Accéder à Google Chat

  2. Cliquez sur Nouveau chat.
  3. Dans le champ Ajouter une ou plusieurs personnes, saisissez le nom de votre application Chat.

  4. Sélectionnez votre application Chat dans les résultats. Un message privé s'ouvre.

  5. Dans le nouveau message privé contenant l'application, saisissez The Eiffel Tower was completed in 1900, puis appuyez sur enter.

    L'application Chat répond avec les réponses des sous-agents Critique et Réviseur.

Pour ajouter des testeurs de confiance et en savoir plus sur le test des fonctionnalités interactives, consultez Tester les fonctionnalités interactives pour les applications Google Chat.

Résoudre les problèmes

Lorsqu'une application ou une fiche Google Chat renvoie une erreur, l'interface Chat affiche le message "Un problème est survenu". ou "Impossible de traiter votre demande". Il arrive que l'UI de Chat n'affiche aucun message d'erreur, mais que l'application ou la fiche Chat produise un résultat inattendu (par exemple, un message de fiche peut ne pas s'afficher).

Bien qu'un message d'erreur ne s'affiche pas dans l'UI Chat, des messages d'erreur descriptifs et des données de journaux sont disponibles pour vous aider à corriger les erreurs lorsque la journalisation des erreurs pour les applications Chat est activée. Pour savoir comment afficher, déboguer et corriger les erreurs, consultez Résoudre les problèmes et corriger les erreurs Google Chat.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans ce tutoriel soient facturées sur votre compte Google Cloud, nous vous recommandons de supprimer le projet Cloud.

  1. Dans la console Google Cloud, accédez à la page Gérer les ressources. Cliquez sur Menu > IAM et administration > Gérer les ressources.

    Accéder au gestionnaire de ressources

  2. Dans la liste des projets, sélectionnez celui que vous souhaitez supprimer, puis cliquez sur Supprimer .
  3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.