Pianificare viaggi con un agente AI accessibile in Google Workspace

Livello di codifica: Avanzato
Durata: 45 minuti
Tipo di progetto: Componente aggiuntivo di Google Workspace che estende Chat, Gmail, Calendar, Drive, Documenti, Fogli e Presentazioni.

Questo tutorial mostra come pubblicare agenti AI su Google Workspace come componenti aggiuntivi di Google Workspace, utilizzando endpoint Apps Script o HTTP. Dopo aver pubblicato il componente aggiuntivo, gli utenti potranno interagire con gli agenti AI all'interno dei loro flussi di lavoro.

Panoramica

In questo tutorial, distribuirai l'esempio Travel Concierge dall'Agent Development Kit (ADK). Travel Concierge è un'intelligenza artificiale multi-agente conversazionale che utilizza strumenti come l'API Places di Google Maps Platform, Google Search Grounding e un server Model Context Protocol (MCP).

Per impostazione predefinita, ADK fornisce interfacce di chat e di testo per gli sviluppatori. In questo tutorial, aggiungerai un'interfaccia utente grafica (GUI) alle applicazioni di Google Workspace a cui i tuoi utenti potranno accedere direttamente in Chat, Gmail, Calendar, Drive, Documenti, Fogli e Presentazioni.

• 

  Figura 1. Utilizzo dell'agente AI di Chat per il brainstorming di idee di viaggio.

• 

  Figura 2. Utilizzo dell'agente AI di Gmail per pianificare un viaggio in base al contesto dell'email selezionata.

Obiettivi

• Configura l'ambiente.
• Distribuisci l'agente AI.
• Impostare il progetto.
• Esegui il deployment su Gmail, Calendar, Drive, Documenti, Fogli e Presentazioni.
• Distribuisci su Chat.
• Testa la soluzione.

Informazioni su questa soluzione

Questa soluzione si basa sulle seguenti tecnologie di base: ADK, Google Cloud e API Google Workspace, Vertex AI Agent Engine e framework delle schede.

Le GUI sono progettate in modo diverso per le applicazioni Chat e non Chat (Gmail, Calendar, Drive, Documenti, Fogli, Presentazioni) per tenere conto delle loro funzionalità e limitazioni specifiche.

Funzionalità

Le seguenti funzionalità dell'applicazione Travel Concierge sono comuni a tutte le applicazioni Google Workspace:

• Sessioni utente persistenti: le sessioni sono gestite da Vertex AI per la persistenza. Ogni utente condivide una sessione su tutte le applicazioni Workspace. Gli utenti possono reimpostare manualmente la sessione per avviare una nuova conversazione.

• Messaggistica avanzata: gli utenti inviano messaggi di testo e ricevono risposte tramite widget di testo avanzato e schede.

• Gestione degli errori: gli errori imprevisti vengono gestiti in modo controllato utilizzando tentativi e stati configurabili nelle risposte.

L'app Chat ha le seguenti funzionalità aggiuntive:

• Messaggistica utente multimodale: gli utenti possono inviare messaggi con allegati, inclusi audio e video registrati direttamente dallo spazio Chat.

• Risposte visivamente più avanzate: le risposte possono essere generate con widget più avanzati, come caroselli con immagini, sfruttando le funzionalità Chat-only del framework Card e più spazio di rendering.

Altre applicazioni hanno queste funzionalità aggiuntive:

• Contesto del profilo Google: gli utenti possono inviare messaggi con le informazioni del loro profilo (in questo esempio, limitate ai compleanni).

• Contesto di Gmail: gli utenti possono inviare messaggi tramite email (limitati a un oggetto e un corpo in questo esempio).

• Accesso allo spazio di Chat dell'agente: gli utenti possono aprire lo spazio di messaggi diretti dell'app Chat in una nuova scheda con un solo clic.

Architettura

L'applicazione Travel Concierge riceve ed elabora gli eventi di interazione del componente aggiuntivo di Google Workspace dalle applicazioni Google Workspace, utilizza Vertex AI per sollecitare l'agente ADK AI e gestire le sessioni utente e si affida alle API di Google Cloud e Google Workspace per raccogliere il contesto e visualizzare le risposte.

I seguenti diagrammi mostrano il flusso principale dell'utente: inviare un messaggio all'agente AI.

HTTP

• 

  Figura 3. L'app Chat completa il contesto con gli allegati del messaggio dell'utente e invia una serie di messaggi con la cronologia delle interazioni del subagente e la risposta complessiva finale in ordine cronologico.

• 

  Figura 4. Le applicazioni non-Chat completano il contesto con il profilo Google dell'utente e la selezione degli elementi, e visualizzano una serie di sezioni con la cronologia delle interazioni con i sub-agenti e la risposta complessiva finale in ordine cronologico inverso.

Apps Script

• 

  Figura 3. L'app Chat completa il contesto con gli allegati del messaggio dell'utente e invia una serie di messaggi con la cronologia delle interazioni del subagente e la risposta complessiva finale in ordine cronologico.

• 

  Figura 4. Le applicazioni non-Chat completano il contesto con il profilo Google dell'utente e la selezione degli elementi, e visualizzano una serie di sezioni con la cronologia delle interazioni con i sub-agenti e la risposta complessiva finale in ordine cronologico inverso.

Prerequisiti

• Un account Google Workspace Business o Enterprise con accesso a Google Chat.

• Un browser web con accesso a Internet.

• Prerequisiti specifici per l'agente Travel Concierge ADK AI

  • Python 3.10+: per l'installazione, seguire le istruzioni sul sito web ufficiale di Python.
  • uv: Per l'installazione, segui le istruzioni sul sito web ufficiale di uv.
  • Google Cloud CLI: per l'installazione, segui le istruzioni sul sito web ufficiale di Google Cloud.

Prepara l'ambiente

Questa sezione mostra come creare e configurare un progetto Google Cloud.

Crea un progetto Google Cloud

Console Google Cloud

1. Nella console di Google Cloud, vai a Menu > IAM e amministrazione > Crea un progetto.

   Vai a Crea un progetto

2. Nel campo Nome progetto, inserisci un nome descrittivo per il tuo progetto.

   Facoltativo: per modificare l'ID progetto, fai clic su Modifica. L'ID del progetto non può essere modificato dopo la creazione del progetto, quindi scegli un ID che soddisfi le tue esigenze per tutta la durata del progetto.

3. Nel campo Posizione, fai clic su Sfoglia per visualizzare le possibili posizioni del tuo progetto. Quindi, fai clic su Seleziona.
   Attenzione: non riesci a trovare la tua organizzazione Google Workspace?
   Ciò significa che non hai eseguito l'accesso a un account Google Workspace. Alcune delle funzionalità descritte nella documentazione per sviluppatori di Google Workspace sono disponibili solo per i progetti associati a un'organizzazione.
4. Fai clic su Crea. La console di Google Cloud ti porta alla pagina Dashboard e il tuo progetto verrà creato in pochi minuti.

Interfaccia a riga di comando gcloud

In uno dei seguenti ambienti di sviluppo, accedi a Google Cloud CLI (gcloud):

• Cloud Shell: per utilizzare un terminale online con la CLI gcloud già configurata, attiva Cloud Shell.
  Attiva Cloud Shell
• Shell locale: per utilizzare un ambiente di sviluppo locale, installa e inizializza la CLI gcloud.
  Per creare un progetto Cloud, usa il comando gcloud projects create:

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID impostando l'ID per il progetto che vuoi creare.

Abilita la fatturazione per il progetto Cloud

Se non riesci a collegare un account di fatturazione, non disponi delle autorizzazioni necessarie per apportare questa modifica. Per ulteriori informazioni, consulta Autorizzazioni necessarie per abilitare la fatturazione.

Console Google Cloud

1. Nella console di Google Cloud, vai a Fatturazione. Fai clic su Menu > Fatturazione > I miei progetti.

   Vai a Fatturazione per i miei progetti

2. In Seleziona un'organizzazione, scegli l'organizzazione associata al tuo progetto Google Cloud.
3. Nella riga del progetto, apri il menu Azioni (), fai clic su Modifica fatturazione e scegli l'account Cloud Billing.
4. Fai clic su Imposta account.

Interfaccia a riga di comando gcloud

1. Per elencare gli account di fatturazione disponibili, eseguire:

   gcloud billing accounts list

2. Collega un account di fatturazione a un progetto Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Sostituisci quanto segue:

   • PROJECT_ID è l'ID progetto del progetto Cloud per il quale vuoi attivare la fatturazione.
   • BILLING_ACCOUNT_ID è l'ID account di fatturazione da collegare al progetto Google Cloud.

Abilita le API di Google Cloud

HTTP

1. Nella console di Google Cloud, abilita le API Vertex AI, Places, People, Google Chat, Gmail, Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry, Cloud Run e i componenti aggiuntivi di Google Workspace.

   Abilita le API

2. Verifica di aver abilitato le API nel progetto Cloud corretto, quindi fai clic su Avanti.

3. Verifica di abilitare le API corrette, poi fai clic su Abilita.

Apps Script

1. Nella console di Google Cloud, abilita le API Vertex AI, Places, People e Google Chat.

   Abilita le API

2. Verifica di aver abilitato le API nel progetto Cloud corretto, quindi fai clic su Avanti.

3. Verifica di aver abilitato le API corrette, quindi fai clic su Abilita.

Ottieni una chiave API di Google Maps Platform Places

1. Nella console di Google Cloud, vai alla pagina Google Maps Platform > Chiavi e credenziali.

   Vai a Chiavi e credenziali

2. La finestra di dialogo Inizia a usare Google Maps Platform mostra la chiave API appena creata, una stringa alfanumerica. Ti servirà nelle sezioni successive.

Nota: se hai già una chiave API adatta, viene visualizzato l'elenco delle chiavi API, non la finestra di dialogo Inizia a utilizzare Google Maps Platform. Seleziona Mostra chiave per visualizzare la chiave.

Crea 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 di Google Cloud, vai a Menu > IAM e amministrazione > Account di servizio.

   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.
   Nota: per impostazione predefinita, Google crea un ID account di servizio univoco. Se desideri modificare l'ID, modificalo nel campo ID account di servizio.
4. (Facoltativo) Assegna ruoli al tuo service account per concedere l'accesso alle risorse del tuo progetto Google Cloud. Per maggiori 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 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 service account per concedere l'accesso alle risorse del tuo 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. Successivamente, crea una chiave privata per l'account di servizio.

Crea una chiave privata

Avviso: questo esempio utilizza una chiave del service account esportata per semplicità. L'esportazione di una chiave privata non è consigliata in produzione perché non dovrebbe essere archiviata in una posizione non sicura, come il controllo del codice sorgente.

Per scoprire di più sulle implementazioni sicure dei service account e sulle best practice, consulta Scegliere quando utilizzare i service account.

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

1. Nella console Google Cloud, vai a 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.

   La nuova coppia di chiavi pubblica/privata viene generata e scaricata sul tuo computer come un 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 Gestione delle chiavi degli account di servizio.

5. Fai clic su Chiudi.

Per ulteriori informazioni sugli account di servizio, consulta Account di servizio nella documentazione di Google Cloud IAM.

Configura la schermata per il consenso OAuth

I componenti aggiuntivi di Google Workspace richiedono una configurazione della schermata di consenso. La configurazione della schermata per il consenso OAuth del componente aggiuntivo definisce ciò che Google mostra agli utenti.

1. Nella console di Google Cloud, vai a 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 viene visualizzato il messaggio Google Auth platform non ancora configurata, fai clic su Inizia:
1. In Informazioni sull'app, nel campo 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. Quindi aggiungi gli ambiti di autorizzazione richiesti dalla tua app. Per saperne di più, consulta la guida completa Configurare il consenso OAuth.

Distribuisci l'agente AI ADK di Travel Concierge

1. Se non l'hai già fatto, autenticati con il tuo account Google Cloud e configura Google Cloud CLI per 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 progetto Cloud che hai creato.

2. Scarica questo repository GitHub

   Scarica

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

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/travel-concierge

4. Crea un nuovo bucket di Cloud Storage dedicato all'agente ADK AI.

   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 desideri utilizzare.
   2. PROJECT_ID con l'ID del progetto Cloud che hai creato.
   3. PROJECT_LOCATION con la posizione del progetto Cloud che hai creato.

5. Impostare le seguenti variabili di ambiente:

   export GOOGLE_GENAI_USE_VERTEXAI=1
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_PLACES_API_KEY=PLACES_API_KEY
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
   export TRAVEL_CONCIERGE_SCENARIO=travel_concierge/profiles/itinerary_empty_default.json

   Sostituisci quanto segue:

   1. PROJECT_ID con l'ID del progetto Cloud che hai creato.
   2. PROJECT_LOCATION con la posizione del progetto Cloud che hai creato.
   3. PLACES_API_KEY con la stringa della chiave API che hai creato.
   4. CLOUD_STORAGE_BUCKET_NAME con il nome del bucket che hai creato.

6. Installa e distribuisci l'agente ADK AI.

   uv sync --group deployment
   uv run python deployment/deploy.py --create

7. Recupera il numero di progetto e l'ID motore dall'ultimo log stampato come PROJECT_NUMBER e ENGINE_ID rispettivamente. Ti serviranno entrambi in un secondo momento per configurare il progetto.

   Created remote agent: projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENGINE_ID

Rivedi il codice di esempio

Facoltativamente, prima di impostare il progetto, prenditi un momento per rivedere e familiarizzare con il codice di esempio ospitato su GitHub.

Python

Visualizza su GitHub

Apps Script

Visualizza su GitHub

Creare e configurare il progetto

Python

1. Scarica questo repository GitHub

   Scarica

2. Nell'ambiente di sviluppo locale che preferisci, estrai il file archivio scaricato e apri la directory add-ons-samples/python/travel-adk-ai-agent.

   unzip add-ons-samples-main.zip
   cd add-ons-samples-main/python/travel-adk-ai-agent

3. Spostare il file chiave JSON credentials.json dall'account di servizio scaricato nei passaggi precedenti alla directory del progetto.

4. Nella console di Google Cloud, vai a Cloud Run:

   Vai a Cloud Run

5. Fai clic su Scrivi una funzione.

6. Nella pagina Crea servizio, configura la funzione:

   1. Nel campo Nome servizio, inserisci travel-concierge-app.
   2. Nell'elenco Regione, seleziona la posizione del progetto Cloud che hai creato, PROJECT_LOCATION.
   3. In Endpoint URL, fai clic su .
   4. Nell'elenco Runtime, seleziona la versione più recente di Python.
   5. Nella sezione Autenticazione, seleziona Consenti accesso pubblico.
   6. Nella sezione Container, volumi, networking, sicurezza, in Risorse:
      1. Nel campo Memoria, seleziona 1 GiB.
      2. Nel campo CPU, seleziona 2.
   7. Fai clic su Crea e attendi che Cloud Run crei il servizio. La console ti reindirizza alla scheda Origine.

7. Nell'ambiente di sviluppo locale che preferisci, esegui il deployment dell'origine del progetto:

   gcloud run deploy travel-concierge-app --quiet --source . \
       --region PROJECT_LOCATION  \
       --function adk_ai_agent  \
       --set-env-vars LOCATION=LOCATION,PROJECT_NUMBER=PROJECT_NUMBER,ENGINE_ID=ENGINE_ID,BASE_URL=BASE_URL

   Sostituisci quanto segue:

   1. PROJECT_LOCATION con la posizione della funzione Cloud Run creata in precedenza.
   2. LOCATION con la posizione del progetto Google Cloud creato nei passaggi precedenti, PROJECT_LOCATION.
   3. PROJECT_NUMBER con il numero di progetto dell'agente AI Travel Concierge ADK di cui è stato eseguito il deployment nei passaggi precedenti.
   4. ENGINE_ID con l'ID motore dell'agente AI ADK Travel Concierge di cui è stato eseguito il deployment nei passaggi precedenti.
   5. BASE_URL con l'URL endpoint che hai copiato in precedenza.

Apps Script

Per creare un progetto Apps Script e configurarlo per utilizzare l'agente Travel Concierge ADK AI distribuito:

1. Fai clic sul pulsante seguente per aprire il progetto Apps Script dell'agente AI ADK Travel Concierge.
   Apri il progetto

2. Fai clic su Panoramica, quindi su Crea una copia.

3. Assegna un nome alla tua copia del progetto Apps Script:

   1. Fai clic su Copia dell'agente AI ADK Travel Concierge.
   2. In Titolo del progetto, digita Travel Concierge ADK AI Agent.
   3. Fai clic su Rinomina.

4. Nel progetto Apps Script, fai clic su Editor e sposta il file VertexAi.gs verso l'alto finché non si trova sopra il file AgentHandler.gs utilizzando l'azione file Sposta file su.

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

6. ENGINE_ID con l'ID motore dell'agente Travel Concierge ADK AI distribuito nei passaggi precedenti, ENGINE_ID.

7. LOCATION con la posizione del progetto Google Cloud creato nei passaggi precedenti, PROJECT_LOCATION.

8. PROJECT_NUMBER con il numero di progetto dell'agente AI ADK Travel Concierge di cui è stato eseguito il deployment nei passaggi precedenti, PROJECT_NUMBER.

9. SERVICE_ACCOUNT_KEY con la chiave JSON dall'account di servizio scaricato nei passaggi precedenti, ad esempio { ... }.

10. Fai clic su Salva proprietà script

11. Nel tuo progetto Apps Script, fai clic su Impostazioni progetto.

12. In Progetto Google Cloud (GCP), fai clic su Modifica progetto.

13. In Numero progetto Google Cloud, incolla il numero di progetto dell'agente AI Travel Concierge ADK di cui è stato eseguito il deployment nei passaggi precedenti, PROJECT_NUMBER.

14. Fai clic su Imposta progetto. Il progetto Cloud e il progetto Apps Script sono ora connessi.

Esegui il deployment su Gmail, Calendar, Drive, Documenti, Fogli, Presentazioni

Python

Utilizza un deployment del componente aggiuntivo Google Workspace per installare il progetto di esempio in tutte le applicazioni Google Workspace (tranne Google Chat) per abilitare i test.

1. Nel tuo ambiente di sviluppo locale preferito, apri il file deployment.json dal codice sorgente del progetto e sostituisci tutte le occorrenze di $BASE_URL con il valore di BASE_URL, l'URL endpoint che hai copiato nei passaggi precedenti.

2. Crea una distribuzione del componente aggiuntivo di Google Workspace denominata travel-concierge-addon:

   gcloud workspace-add-ons deployments create travel-concierge-addon \
       --deployment-file=deployment.json

3. Installa la distribuzione del componente aggiuntivo Google Workspace:

   gcloud workspace-add-ons deployments install travel-concierge-addon

Apps Script

Installa il progetto Apps Script in tutte le applicazioni di Google Workspace (tranne Google Chat) per abilitare i test.

1. Nel progetto Apps Script, fai clic su Distribuisci > Distribuzioni di prova, quindi su Installa.

Il componente aggiuntivo è ora accessibile dalle barre laterali dell'applicazione Google Workspace.

Distribuisci in Chat

Python

Installa il progetto di esempio in Chat utilizzando l'URL dell'endpoint per abilitare i test.

1. Nella console, cerca Google Chat API, fai clic su API Google Chat, quindi su Gestisci e Configurazione.

   Vai alla pagina di configurazione dell'API Google Chat

2. Configura l'app Chat:

   1. Nel campo Nome app, inserisci Travel ADK AI Agent.
   2. Nel campo URL avatar, inserisci https://goo.gle/3SfMkjb.
   3. Nel campo Descrizione, inserisci Travel ADK AI Agent.
   4. In Impostazioni di connessione, seleziona URL endpoint HTTP.
   5. In Trigger, seleziona Utilizza un URL dell'endpoint HTTP comune per tutti i trigger.
   6. Nel campo HTTP endpoint URL (URL endpoint HTTP), incolla l'Endpoint URL (URL endpoint) che hai copiato in precedenza, BASE_URL.
   7. Registra un comando rapido che l'app Chat completamente implementata utilizza:
      1. Nella sezione Comandi, fai clic su Aggiungi un comando.
      2. In ID comando, digita 1.
      3. In Descrizione, digita Reset session.
      4. In Tipo di comando, seleziona Comando rapido.
      5. In Nome, digita Reset session.
      6. Fai clic su Fine. Il comando rapido viene registrato ed elencato.
   8. In Visibilità, seleziona Rendi questa app Chat disponibile a persone e gruppi specifici nel tuo dominio Workspace e inserisci il tuo indirizzo email.
   9. In Log, seleziona Errori di log in Logging.
   10. Fai clic su Salva.

Apps Script

Installa il progetto Apps Script in Chat utilizzando l'ID distribuzione Head per abilitare i test.

1. Nel progetto Apps Script, fai clic su Distribuisci > Distribuzioni di prova, quindi su Copia in ID distribuzione principale.

2. Nella console, cerca Google Chat API, fai clic su API Google Chat, quindi su Gestisci e Configurazione.

   Vai alla pagina di configurazione dell'API di Google Chat

3. Configura l'app Chat:

   1. Nel campo Nome app, inserisci Travel ADK AI Agent.
   2. Nel campo URL avatar, inserisci https://goo.gle/3SfMkjb.
   3. Nel campo Descrizione, inserisci Travel ADK AI Agent.
   4. Nella sezione Impostazioni di connessione, seleziona Apps Script.
   5. Nel campo ID deployment, incolla l'ID deployment head che hai copiato in precedenza.
   6. Registra un comando rapido che l'app di chat completamente implementata utilizza:
      1. In Comandi, fai clic su Aggiungi un comando.
      2. In ID comando, digita 1.
      3. In Descrizione, digita Reset session.
      4. In Tipo di comando, seleziona Comando rapido.
      5. In Nome, digita Reset session.
      6. Fai clic su Fine. Il comando rapido viene registrato ed elencato.
   7. In Visibilità, seleziona Rendi questa app Chat disponibile a persone e gruppi specifici nel tuo dominio Workspace e inserisci il tuo indirizzo email.
   8. In Log, seleziona Errori di log in Logging.
   9. Fai clic su Salva.

L'app è ora accessibile da Google Chat.

1. Apri Google Chat.

   Vai a Google Chat

2. Crea lo spazio Chat DM:

   1. Fai clic su Nuova chat.
   2. Digita e seleziona l'app Travel ADK AI Agent nella ricerca.
   3. Nella finestra di dialogo Install app, fai clic su Installa app.
   4. La finestra di dialogo Install app si chiude e viene selezionato lo spazio Chat DM appena creato.

L'app Chat è pronta a rispondere ai messaggi.

Testare l'agente

1. Apri Gmail.

   Vai a Gmail

2. Invia la seguente email al tuo indirizzo:

   • Oggetto: You need to travel to Paris
   • Corpo: Please be there between 11/25/2025 and 11/30/2025!

3. Apri il componente aggiuntivo Agente AI ADK per i viaggi dalla barra laterale.

4. Fai clic su Concedi autorizzazioni per completare la configurazione del componente aggiuntivo.

5. Fai clic su Invia dopo aver configurato la seguente richiesta all'agente:

   • Messaggio: Please help me plan this travel!
   • Contesto: seleziona Email corrente

   La barra laterale viene aggiornata con la risposta dell'agente.

   

6. Fai clic su Apri chat per essere reindirizzato allo spazio DM della chat.

7. Fai clic su + > Reimposta sessione.

   Ricevi un nuovo messaggio che conferma l'operazione: OK, let's start from the beginning, what can I help you with?

8. Invia il messaggio Give me ideas.

   Ricevi nuovi messaggi con la risposta dell'agente.

   

9. Invia il messaggio I want to go there! dopo aver caricato una foto di una località qualsiasi, ad esempio la Torre Eiffel.

   Ricevi nuovi messaggi con la risposta dell'agente.

   

Nota: il componente aggiuntivo Travel ADK AI Agent può essere aperto anche dalla barra laterale in Calendario, Drive, Documenti, Fogli e Presentazioni, in modo simile a come avviene in Gmail.

Limitazioni

HTTP

Nelle applicazioni Google Workspace diverse da Chat, l'agente AI presenta le seguenti limitazioni:

• È sincrono: le barre laterali possono essere aggiornate solo in risposta alle interazioni dell'utente, quindi le risposte dell'agente AI vengono visualizzate solo dopo il completamento (nessuno streaming).

• Potrebbe scadere: gli aggiornamenti della barra laterale scadono quando impiegano più di qualche minuto per essere completati.

Queste limitazioni non esistono in Chat.

Apps Script

In tutte le applicazioni Google Workspace, l'agente AI richiama le API REST di Vertex AI tramite UrlFetchApp, il che comporta le seguenti limitazioni:

• È sincrono: le risposte dell'agente AI vengono restituite solo dopo il completamento (nessun streaming).

• Può andare in timeout: l'agente AI va in timeout quando impiega più di un minuto circa per completare l'operazione.

Personalizzazione

Questa soluzione supporta gli agenti AI ADK ospitati in Vertex AI Agent Engine, un sottoinsieme delle UI delle applicazioni Google Workspace e rendering delle risposte specifici per le risposte dell'esempio Travel Concierge. La soluzione utilizza un framework estensibile, quindi puoi personalizzarla modificando i seguenti file:

Python

• main.py: definisce le UI principali e la logica delle interazioni utente (gestori di eventi di Google Workspace). Un'estensione tipica sarebbe quella di abilitare i documenti di Drive come funzionalità di contesto per l'applicazione Drive, in modo simile a quanto fatto con i messaggi di Gmail per l'applicazione Gmail.

• vertex_ai.py: gestisce le sessioni, le risposte e gli errori dell'agente AI e definisce le interfacce specifiche di Vertex AI da implementare per supportare le interazioni e il rendering delle risposte dell'agente. Le estensioni tipiche sarebbero l'aggiunta del supporto per sessioni multiple per conversazioni utente separate e altre piattaforme di gestione degli agenti di intelligenza artificiale.

• agent_handler.py: implementa le interfacce specifiche di Vertex AI definite in vertex_ai.py nei casi specifici delle applicazioni Chat e non Chat. Un'estensione tipica sarebbe quella di aggiungere pulsanti che consentano agli utenti di inviare feedback sulle risposte degli agenti di intelligenza artificiale.

• google_workspace.py: implementa interazioni tra piattaforma di gestione degli agenti non AI tramite chiamate API. In questo esempio vengono utilizzate solo le API Google Workspace per raccogliere i dettagli del contesto ed eseguire azioni. Un'estensione tipica sarebbe quella di aggiungere funzioni per recuperare dati aziendali da Google Calendar o da un Customer Relationship Management (CRM).

• travel_agent_ui_render.gs: implementa il rendering delle risposte specifiche di Travel Concierge per i subagenti e le applicazioni Workspace. Le estensioni tipiche sarebbero l'aggiunta del supporto per nuovi rendering di risposta per visualizzare graficamente le opzioni di volo e altri agenti di intelligenza artificiale.

Apps Script

• Code.gs: definisce le UI principali e la logica delle interazioni utente (gestori di eventi di Google Workspace). Un'estensione tipica sarebbe quella di attivare i documenti di Drive come funzionalità contestuale per l'applicazione Drive, in modo simile a quanto fatto con i messaggi Gmail per l'applicazione Gmail.

• VertexAi.gs: gestisce le sessioni, le risposte e gli errori dell'agente AI e definisce le interfacce specifiche di Vertex AI da implementare per supportare le interazioni e il rendering delle risposte dell'agente. Le estensioni tipiche consistono nell'aggiunta del supporto per più sessioni per conversazioni separate degli utenti e altre piattaforme di gestione degli agenti AI.

• AgentHandler.gs: implementa le interfacce specifiche di Vertex AI definite in VertexAi.gs nei casi specifici delle applicazioni Chat e non Chat. Un'estensione tipica sarebbe quella di aggiungere pulsanti che consentano agli utenti di inviare feedback sulle risposte degli agenti di intelligenza artificiale.

• GoogleWorkspace.gs: implementa interazioni tra piattaforma di gestione di agenti non AI tramite chiamate API. In questo esempio vengono utilizzate solo le API di Google Workspace per raccogliere dettagli contestuali ed eseguire azioni. Un'estensione tipica sarebbe quella di aggiungere funzioni per recuperare dati aziendali da Google Calendar o da un Customer Relationship Management (CRM).

• TravelAgentUiRender.gs: implementa rendering di risposta specifici di Travel Concierge per i subagenti e le applicazioni Workspace. Le estensioni tipiche sarebbero l'aggiunta del supporto per nuovi rendering di risposta per visualizzare graficamente le opzioni di volo e altri agenti di intelligenza artificiale.

Esegui la pulizia

Per evitare di incorrere in addebiti sul tuo account Google Cloud per le 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, eliminandolo eliminerai anche qualsiasi altro lavoro svolto 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 del 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 di Google Cloud, vai alla pagina Gestisci risorse. Fai clic su Menu > IAM e amministrazione > Gestisci risorse.

   Vai a Gestione risorse

2. Nell'elenco dei progetti, seleziona il progetto che desideri eliminare, quindi fai clic su Elimina .
3. Nella finestra di dialogo, digita l'ID del progetto e poi fai clic su Arresta per eliminare il progetto.

Argomenti correlati

• Verificare l'accuratezza delle affermazioni con un agente AI ADK e il modello Gemini
• Integrare i concetti fondamentali dell'intelligenza artificiale nelle app di chat
• Crea un'app di chat come componente aggiuntivo di Google Workspace con Apps Script