Crea un'app Google Chat con un agente Agent2Agent

Anteprima di Vertex AI Agent Builder: Lo sviluppo e l'utilizzo di un agente Agent2Agent (A2A) sono in anteprima. Consulta la documentazione completa.

Questa pagina spiega come creare un componente aggiuntivo di Google Workspace che funziona in Google Chat e interagisce con un agente AI che utilizza il protocollo Agent2Agent (A2A). Sviluppi l'agente utilizzando l' Agent Development Kit (ADK), e lo ospiti in Vertex AI Agent Engine.

Nota: in Google Chat, gli utenti vedono i componenti aggiuntivi come app di Google Chat. Puoi anche creare la tua app di Chat utilizzando gli eventi di interazione dell'API Google Chat. Per saperne di più, consulta la panoramica Estendere Google Chat.

Gli agenti AI percepiscono autonomamente il loro ambiente, ragionano ed eseguono azioni complesse, in più passaggi per raggiungere un obiettivo definito. In questo tutorial, esegui il deployment dell' esempio multi-agente LLM Auditor che critica e rivede i fatti utilizzando Gemini e la base di conoscenza della Ricerca Google.

Il seguente diagramma mostra l'architettura e il pattern di messaggistica:

Nel diagramma, un utente che interagisce con un' app di Chat implementata con un agente A2A ha il seguente flusso di informazioni:

1. Un utente invia un messaggio a un'app di Chat, in un messaggio diretto o in uno spazio di Chat.
2. La logica dell'app di Chat implementata in Apps Script o come server web con endpoint HTTP riceve ed elabora il messaggio.
3. L'agente A2A ospitato con Vertex AI Agent Engine riceve ed elabora l'interazione.
4. (Facoltativo) L'app di Chat o l'agente AI possono integrarsi con i servizi Google Workspace, come Calendar o Fogli, o altri servizi Google, come Google Maps o YouTube.
5. L'app di Chat invia le risposte in modo asincrono, utilizzando l'API Google Chat per comunicare l'avanzamento dell'agente AI.
6. Le risposte vengono inviate all'utente.

Obiettivi

• Configurare l'ambiente.
• Eseguire il deployment dell'agente A2A.
• Eseguire il deployment dell'app di Chat.
• Configurare l'app di Chat.
• Testare l'app di Chat.

Prerequisiti

• Un account Google Workspace Business o Enterprise con accesso a Google Chat.
• Un progetto Google Cloud con la fatturazione abilitata. Per verificare che un progetto esistente abbia la fatturazione abilitata, consulta Verifica lo stato di fatturazione dei progetti. Per creare un progetto e configurare la fatturazione, consulta Crea un progetto Google Cloud.
• Prerequisiti dell'agente ADK LLM Auditor
  • Python 3.11+: per l'installazione, segui le istruzioni sul sito web ufficiale di Python.
  • Python Poetry: per l'installazione, segui le istruzioni sul sito web ufficiale di Poetry.
  • Google Cloud CLI: per l'installazione, segui le istruzioni sul sito web ufficiale di Google Cloud.

Configurare l'ambiente

Abilitare le API Google Cloud

Prima di utilizzare le API Google, devi attivarle in un progetto Google Cloud. Puoi attivare una o più API in un singolo progetto Google Cloud.

• Nella console Google Cloud, abilita le API Google Chat, Vertex AI e Cloud Resource Manager.

  Abilita le API

Configurare la schermata per il consenso OAuth

Tutte le app che utilizzano OAuth 2.0 richiedono una configurazione della schermata per il consenso. La configurazione della schermata per il consenso OAuth della tua app definisce ciò che viene visualizzato agli utenti e ai revisori dell'app e registra l'app in modo che tu possa pubblicarla in un secondo momento.

1. Nella console Google Cloud, vai a Menu > Google Auth platform > Branding.

   Vai a Branding

2. Se hai già configurato il Google Auth platform, puoi configurare le seguenti impostazioni della schermata per il consenso OAuth in Branding, Pubblico e Accesso ai dati. Se vedi un messaggio che indica che Google Auth platform non è ancora configurato, fai clic su Inizia:
1. In Informazioni sull'app, nel campo Nome app, inserisci un nome per l'app.
2. In Email di assistenza utente, scegli un indirizzo email di assistenza a cui gli utenti possono contattarti se hanno domande sul loro consenso.
3. Fai clic su Avanti.
4. In Pubblico, seleziona Interno.
5. Fai clic su Avanti.
6. In Dati di contatto, inserisci un indirizzo email a cui puoi ricevere notifiche in merito a eventuali modifiche al tuo progetto.
7. Fai clic su Avanti.
8. In Fine , esamina le Norme relative ai dati utente dei servizi API di Google e, se le accetti, seleziona Accetto le Norme relative ai dati utente: servizi API di Google.
9. Fai clic su Continua.
10. Fai clic su Crea.
3. Per il momento, puoi saltare l'aggiunta di ambiti. In futuro, quando crei un'app da utilizzare al di fuori della tua organizzazione Google Workspace, devi impostare Tipo utente su Esterno. Aggiungi poi gli ambiti di autorizzazione richiesti dalla tua app. Per saperne di più, consulta la guida completa Configurare il consenso OAuth guide.

Creare un account di servizio nella console Google Cloud

Crea un nuovo account di servizio con il ruolo Vertex AI User seguendo questi passaggi:

Console Google Cloud

1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Account di servizio.

   Vai a Service account

2. Fai clic su Crea account di servizio.
3. Inserisci i dettagli dell'account di servizio, quindi fai clic su Crea e continua.
   Nota: per impostazione predefinita, Google crea un ID account di servizio univoco. Se vuoi modificare l'ID, fallo nel campo ID account di servizio.
4. (Facoltativo) Assegna ruoli al tuo account di servizio per concedere l'accesso alle risorse del progetto Google Cloud. Per maggiori dettagli, consulta Concessione, modifica e revoca dell'accesso alle risorse.
5. Fai clic su Continua.
6. (Facoltativo) Inserisci utenti o gruppi che possono gestire ed eseguire azioni con questo account di servizio. Per maggiori dettagli, consulta Gestire la simulazione dell'identità dei service account.
7. Fai clic su Fine. Prendi nota dell'indirizzo email dell'account di servizio.

Interfaccia a riga di comando gcloud

1. Crea l'account di servizio:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. (Facoltativo) Assegna ruoli al tuo account di servizio per concedere l'accesso alle risorse del progetto Google Cloud. Per maggiori dettagli, consulta Concessione, modifica e revoca dell'accesso alle risorse.

L'account di servizio viene visualizzato nella pagina degli account di servizio.

Crea una chiave privata

Avvertenza: questo esempio utilizza una chiave dell'account di servizio esportata per semplicità. L'esportazione di una chiave privata non è consigliata in produzione perché non deve essere archiviata in una posizione non sicura, ad esempio il controllo del codice sorgente.

Per saperne di più sulle implementazioni sicure degli account di servizio e sulle best practice, consulta Scegliere quando utilizzare gli account di servizio.

Per creare e scaricare una chiave privata per l'account di servizio:

1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Account di servizio.

   Vai a Service account

2. Seleziona il tuo account di servizio.
3. Fai clic su Chiavi > Aggiungi chiave > Crea nuova chiave.
4. Seleziona JSON, quindi fai clic su Crea.

   Una nuova coppia di chiavi pubblica/privata viene generata e scaricata sul tuo computer come nuovo file. Salva il file JSON scaricato come credentials.json nella tua directory di lavoro. Questo file è l'unica copia di questa chiave. Per informazioni su come archiviare la chiave in modo sicuro, consulta Gestire le chiavi degli account di servizio.

5. Fai clic su Chiudi.

Per saperne di più sugli account di servizio, consulta la documentazione di Google Cloud IAM.

Eseguire il deployment dell'agente A2A

1. Se non l'hai ancora fatto, esegui l'autenticazione con il tuo account Google Cloud e configura Google Cloud CLI in modo da utilizzare il tuo progetto Google Cloud.

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

   Sostituisci PROJECT_ID con l'ID del tuo progetto Cloud.

2. Scarica il repository GitHub degli esempi ADK utilizzando questo pulsante:

   Scarica adk-samples

3. Nell'ambiente di sviluppo locale che preferisci, estrai il file di archivio scaricato e apri la directory adk-samples/python/agents/llm-auditor.

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

4. Aggiorna l'implementazione per eseguire il deployment dell'agente ADK come agente remoto A2A:

   1. pyproject.toml: aggiungi le dipendenze ADK e A2A SDK nel gruppo di deployment.

      apps-script/chat/a2a-ai-agent/llm-auditor/pyproject.toml

      Visualizza su GitHub
      [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 = "[e-mail]" },
          { name = "Cyrus Rashtchian", email = "[e-mail]" },
          { name = "Da-Cheng Juan", email = "[e-mail]" },
          { name = "Ivan Kuznetsov", email = "[e-mail]" },
      ]
      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: sostituisci il deployment dell'app ADK con un agente e una scheda A2A.

      apps-script/chat/a2a-ai-agent/llm-auditor/deployment/deploy.py

      Visualizza su GitHub
      # 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. Crea un nuovo bucket Cloud Storage dedicato all'agente ADK.

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

   Sostituisci quanto segue:

   1. CLOUD_STORAGE_BUCKET_NAME con un nome bucket univoco che vuoi utilizzare.
   2. PROJECT_ID con l'ID del tuo progetto Cloud.
   3. PROJECT_LOCATION con la località del tuo progetto Cloud.

6. Imposta le seguenti variabili di ambiente:

   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

   Sostituisci quanto segue:

   1. CLOUD_STORAGE_BUCKET_NAME con il nome del bucket che hai creato.
   2. PROJECT_ID con l'ID del tuo progetto Cloud.
   3. PROJECT_LOCATION con la località del tuo progetto Cloud.

7. Installa ed esegui il deployment dell'agente ADK dall'ambiente virtuale.

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

8. Recupera l'ID agente. Ti servirà in un secondo momento, quando configurerai l' app di Chat.

   python3 deployment/deploy.py --list

Creare e configurare il progetto dell'app di Chat

1. Fai clic sul seguente pulsante per aprire il progetto Apps Script Guida rapida per l'agente AI A2A.

   Apri il progetto

2. Fai clic su Panoramica > Crea una copia.

3. Nel progetto Apps Script, fai clic su Impostazioni progetto > Modifica proprietà script > Aggiungi proprietà script per aggiungere le seguenti proprietà script:

   1. REASONING_ENGINE_RESOURCE_NAME con il nome della risorsa dell'agente Vertex AI copiato nei passaggi precedenti.
   2. SERVICE_ACCOUNT_KEY con la chiave JSON dell'account di servizio scaricata nei passaggi precedenti, ad esempio { ... }.

4. Fai clic su Salva proprietà script.

5. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Impostazioni.

   Vai a IAM e amministrazione > Impostazioni

6. Nel campo Numero progetto, copia il valore.

7. Nel progetto Apps Script, fai clic su Impostazioni progetto.

8. In Progetto Google Cloud Platform (Google Cloud), fai clic su Modifica progetto.

9. In Numero progetto Google Cloud, incolla il numero del progetto Google Cloud copiato nei passaggi precedenti.

10. Fai clic su Imposta progetto. Il progetto Cloud e il progetto Apps Script sono ora collegati.

Creare un deployment di test

Hai bisogno di un ID deployment per questo progetto Apps Script, in modo da poterlo utilizzare nel passaggio successivo.

Per ottenere l'ID deployment principale:

1. Nel progetto Apps Script dell'app di Chat, fai clic su Esegui il deployment > Deployment di test.
2. In ID deployment principale, fai clic su Copia.
3. Fai clic su Fine.

Configurare l'app di Chat

Utilizzando il deployment di Apps Script, segui questi passaggi per eseguire il deployment dell'app Google Chat per i test:

1. Nella console, cerca Google Chat API e fai clic su Google Chat API.
2. Fai clic su Gestisci.

3. Fai clic su Configurazione e configura l'app di Chat:

   1. Nel campo Nome app, inserisci A2A Quickstart.
   2. Nel campo URL avatar, inserisci https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
   3. Nel campo Descrizione, inserisci A2A Quickstart.
   4. In Funzionalità, seleziona Partecipa a spazi e conversazioni di gruppo.
   5. In Impostazioni di connessione, seleziona Progetto Apps Script.
   6. Nel campo ID deployment, incolla l'ID deployment principale che hai copiato in precedenza.
   7. In Visibilità, seleziona Persone e gruppi specifici nel tuo dominio e inserisci la tua email.

4. Fai clic su Salva.

L'app di Chat è pronta a rispondere ai messaggi.

Testare l'app di Chat

Per testare l'app di Chat, apri uno spazio di messaggi diretti con l'app di Chat e invia un messaggio:

1. Apri Google Chat utilizzando l'account Google Workspace che hai fornito quando ti sei aggiunto come tester di fiducia.

   Vai a Google Chat

2. Fai clic su Nuova chat.
3. Nel campo Aggiungi una o più persone, digita il nome della tua app di Chat.

4. Seleziona l'app di Chat dai risultati. Si apre un messaggio diretto.

   Nota: se non vedi la tua app di Chat nell'elenco dei risultati, assicurati di aver incluso il tuo account Google Workspace nelle impostazioni di Visibilità della pagina di Configurazione dell'API Chat nella console Google Cloud.

5. Nel nuovo messaggio diretto con l'app, digita The Eiffel Tower was completed in 1900 e premienter.

   L'app di Chat risponde con le risposte dei sotto-agenti Critic e Reviser.

Per aggiungere tester di fiducia e saperne di più sui test delle funzionalità interattive, consulta Testare le funzionalità interattive per le app di Google Chat.

Risoluzione dei problemi

Quando un'app o scheda di Google Chat restituisce un errore, l' interfaccia di Chat mostra un messaggio che indica "Si è verificato un problema" o "Impossibile elaborare la richiesta". A volte l'interfaccia utente di Chat non mostra alcun messaggio di errore, ma l'app o la scheda di Chat produce un risultato imprevisto; ad esempio, un messaggio della scheda potrebbe non essere visualizzato.

Anche se un messaggio di errore potrebbe non essere visualizzato nell'interfaccia utente di Chat, sono disponibili messaggi di errore descrittivi e dati di log per aiutarti a correggere gli errori quando la registrazione degli errori per le app di Chat è attivata. Per assistenza nella visualizzazione, nel debug e nella correzione degli errori, consulta Risolvere e correggere gli errori di Google Chat.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, ti consigliamo di eliminare il progetto Cloud.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per questo tutorial, quando lo eliminerai, eliminerai anche tutto il lavoro effettuato nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL su appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più tutorial e guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. Nella console Google Cloud, vai alla pagina Gestisci risorse. Fai clic su Menu > IAM e amministrazione > Gestisci risorse.

   Vai a Resource Manager

2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina .
3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

Argomenti correlati

• Creare un'app Google Chat con un agente AI ADK
• Verificare l'esattezza delle affermazioni con un agente AI ADK e un modello Gemini
• Pianificare i viaggi con un agente AI accessibile in Google Workspace
• Integrare i concetti fondamentali di AI nelle app di Chat
• Rispondere alle domande in base alle conversazioni di Chat con un'app di Chat AI di Gemini
• Rispondere agli incidenti con Google Chat, Vertex AI, Apps Script e autenticazione utente
• Gestire i progetti con Google Chat, Vertex AI e Firestore