Crea un'app Google Chat con un agente Agent2UI

Questa pagina spiega come creare un componente aggiuntivo di Google Workspace che funzioni in Google Chat e interagisca con un agente AI che utilizza il protocollo Agent2UI (A2UI). L'agente viene sviluppato utilizzando l'Agent Development Kit (ADK) e ospitato in Vertex AI Agent Engine.

Gli agenti di intelligenza artificiale percepiscono autonomamente l'ambiente circostante, ragionano ed eseguono azioni complesse e articolate in più fasi per raggiungere un obiettivo definito. In questo tutorial, implementerai un agente di intelligenza artificiale di base che restituisce informazioni statiche sul profilo recuperate da uno strumento.

A2UI consente agli agenti di intelligenza artificiale di generare interfacce utente adattive, ricche e interattive, che vengono visualizzate in modo nativo. È quindi possibile concentrarsi sulla logica degli agenti di intelligenza artificiale, non sulle interfacce utente.

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 A2UI 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 Chat implementata in Apps Script o come server web con endpoint HTTP riceve ed elabora il messaggio.
3. L'agente A2UI ospitato con Vertex AI Agent Engine riceve ed elabora l'interazione.
4. Se vuoi, l'app Chat o l'agente AI possono integrarsi con i servizi Google Workspace, come Calendar o Fogli, o con altri servizi Google, come Google Maps o YouTube.
5. L'app Chat genera e invia risposte adattive in modo asincrono, utilizzando l'API Google Chat per comunicare lo stato di avanzamento dell'agente AI.
6. Le risposte vengono inviate all'utente.

Obiettivi

• Configurare l'ambiente.
• Esegui il deployment dell'agente A2UI.
• Esegui il deployment dell'app Chat.
• Configura l'app Chat.
• Testa l'app 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 la fatturazione sia abilitata per un progetto esistente, consulta Verificare lo stato di fatturazione dei progetti. Per creare un progetto e impostare la fatturazione, consulta Creare un progetto Google Cloud.
• Python 3.11+: per l'installazione, seguire le istruzioni sul sito web ufficiale di Python.
• Python Poetry: per l'installazione, seguire le istruzioni sul sito web ufficiale di Poetry.
• Google Cloud CLI: per l'installazione, segui le istruzioni sul sito web ufficiale di Google Cloud.

Configura l'ambiente

Abilita le API di Google Cloud

Prima di utilizzare le API di Google, è necessario attivarle in un progetto Google Cloud. È possibile attivare una o più API in un singolo progetto Google Cloud.

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

  Abilita le API

Configura la schermata per il consenso OAuth

Tutte le app che utilizzano OAuth 2.0 richiedono la configurazione della schermata di consenso. La configurazione della schermata di consenso OAuth della tua app definisce cosa viene visualizzato agli utenti e ai revisori dell'app e registra la tua app in modo da poterla pubblicare in un secondo momento.

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

   Vai a Branding

2. Se hai già configurato Google Auth platform, puoi configurare le seguenti impostazioni della schermata di consenso OAuth in Branding, Pubblico e Accesso ai dati. Se vedi un messaggio che dice Google Auth platform non ancora configurato, fai clic su Inizia:
1. In Informazioni app, in Nome app, inserisci un nome per l'app.
2. In Email dell'assistenza utente, scegli un indirizzo email dell'assistenza a cui gli utenti possono contattarti in caso di domande sul loro consenso.
3. Fai clic su Avanti.
4. Nella sezione Pubblico, seleziona Interno.
5. Fai clic su Avanti.
6. In Informazioni di contatto, inserisci un indirizzo email a cui ricevere notifiche in caso di 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 dei servizi API di Google.
9. Fai clic su Continua.
10. Fai clic su Crea.
3. Per ora puoi saltare l'aggiunta degli ambiti. In futuro, quando crei un'app da utilizzare al di fuori della tua organizzazione Google Workspace, devi modificare il Tipo di utente in Esterno. Poi aggiungi gli ambiti di autorizzazione richiesti dalla tua app. Per saperne di più, consulta la guida completa Configurare il consenso OAuth.

Crea un service account nella console Google Cloud

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

Console Google Cloud

1. Nella console Google Cloud, vai a Menu menu > IAM e amministrazione > Service account.

   Vai a Service account

2. Fai clic su Crea account di servizio.
3. Compila i dettagli del service account, quindi fai clic su Crea e continua.
4. (Facoltativo) Assegna ruoli al service account per concedere l'accesso alle risorse del progetto Google Cloud. Per ulteriori dettagli, consulta Concessione, modifica e revoca dell'accesso alle risorse.
5. Fai clic su Continua.
6. (Facoltativo) Inserisci gli utenti o i gruppi che possono gestire ed eseguire azioni con questo service account. Per maggiori dettagli, consulta Gestione della simulazione dell'identità dei service account.
7. Fai clic su Fine. Prendi nota dell'indirizzo email del service account.

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 service account per concedere l'accesso alle risorse del progetto Google Cloud. Per ulteriori 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

Per creare e scaricare una chiave privata per il service account, segui questi passaggi:

1. Nella console Google Cloud, vai a Menu menu > IAM e amministrazione > Service account.

   Vai a Service account

2. Seleziona il tuo service account.
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 directory di lavoro. Questo file è l'unica copia di questa chiave. Per informazioni su come archiviare la chiave in modo sicuro, consulta la sezione Gestione delle chiavi degli account di servizio.

5. Fai clic su Chiudi.

Per saperne di più sui service account, consulta la sezione Service account nella documentazione di Google Cloud IAM.

Esegui il deployment dell'agente A2UI

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 googleworkspace/add-ons-samples utilizzando questo pulsante:

   Scarica repository

3. Nell'ambiente di sviluppo locale che preferisci, estrai il file archivio scaricato e apri la directory 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. 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 di bucket univoco che vuoi utilizzare.
   2. PROJECT_ID: l'ID del tuo progetto Cloud.
   3. PROJECT_LOCATION: la posizione del tuo progetto Cloud.

5. 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 posizione del tuo progetto Cloud.

6. Installa e distribuisci l'agente ADK dall'ambiente virtuale.

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

7. Recupera l'ID dell'agente. Ti servirà più tardi, quando configurerai l'app Chat.

   python3 deployment/deploy.py --list

Crea e configura il progetto dell'app Chat

1. Fare clic sul pulsante seguente per aprire il progetto Apps Script A2UI AI Agent Quickstart.

   Apri il progetto

2. Fai clic su info_outline Panoramica > Crea una copia.

3. Nel tuo 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 agente Vertex AI copiato nei passaggi precedenti.
   2. SERVICE_ACCOUNT_KEY con la chiave JSON dall'account di servizio scaricato nei passaggi precedenti, ad esempio { ... }.

4. Fai clic su Salva proprietà script.

5. Nella console di Google Cloud, vai a Menu 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 (GCP), fai clic su Modifica progetto.

9. In Numero progetto GCP, 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 connessi.

Crea un deployment di test

Per questo progetto Apps Script è necessario un ID deployment, in modo da poterlo utilizzare nel passaggio successivo.

Per ottenere l'ID deployment principale:

1. Nel progetto Apps Script dell'app Chat, fai clic su Deployment > Test dei deployment.
2. In ID deployment head, fai clic su Copia.
3. Fai clic su Fine.

Configurare l'app 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 API Google Chat.
2. Fai clic su Gestisci.

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

   1. Nel campo Nome app, inserisci A2UI Quickstart.
   2. Nel campo URL avatar, inserisci https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
   3. Nel campo Descrizione, inserisci A2UI 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 il tuo indirizzo email.

4. Fai clic su Salva.

L'app Chat è pronta a rispondere ai messaggi.

Testare l'app 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 attendibile.

   Vai a Google Chat

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

4. Seleziona la tua app Chat dai risultati. Si apre un messaggio diretto.

5. Nel nuovo messaggio diretto con l'app, digita Hello! e premi enter.

   L'app Chat risponde a un messaggio con un testo di saluto e una scheda contenente il nome del profilo, l'immagine e il pulsante LinkedIn.

6. Aggiornare l'implementazione dell'agente A2UI per iniziare a restituire anche il titolo del profilo.

   Nell'ambiente di sviluppo locale, apri il file a2ui/agent.py e rimuovi il commento dalla riga nello strumento che aggiunge il titolo ai dati restituiti.

   apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py

   Visualizza su GitHub
   # 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. Aggiornare l'ADK precedentemente distribuito con la nuova versione dell'implementazione.

   python3 deployment/deploy.py --update --resource_id=RESOURCE_ID

   Sostituisci RESOURCE_ID con il nome della risorsa dell'agente Vertex AI copiato nei passaggi precedenti.

8. Nel messaggio diretto con l'app, digita Hello again! e premi enter.

   L'app Chat risponde a un messaggio con del testo e una scheda contenente il titolo del profilo.

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

Risoluzione dei problemi

Quando un'app o una scheda di Google Chat restituisce un errore, l'interfaccia di Chat visualizza un messaggio che dice "Si è verificato un errore". o "Impossibile elaborare la tua richiesta." A volte l'interfaccia utente della chat non visualizza alcun messaggio di errore, ma l'app o la scheda Chat produce un risultato inaspettato; ad esempio, un messaggio sulla scheda potrebbe non essere visualizzato.

Sebbene un messaggio di errore potrebbe non essere visualizzato nell'interfaccia utente della chat, sono disponibili messaggi di errore descrittivi e dati di registro 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 Risoluzione dei problemi e correzione degli 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.

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

   Vai a Resource Manager

2. Nell'elenco dei progetti, seleziona quello da eliminare e fai clic su Elimina delete.
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
• Creare un'app Google Chat con un agente A2A
• Verificare l'accuratezza delle affermazioni con un agente AI ADK e il modello Gemini
• Pianificare i viaggi con un agente AI accessibile in Google Workspace
• Integrare i concetti fondamentali dell'AI nelle app di chat
• Rispondere a domande basate sulle conversazioni di Chat con un'app Gemini AI Chat
• Rispondere agli incidenti con Google Chat, Vertex AI, Apps Script e l'autenticazione utente
• Gestire i progetti con Google Chat, Vertex AI e Firestore