Pianificare viaggi con un agente AI accessibile in Google Workspace

HTTP

Apps Script

HTTP

1. Nella console 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 componenti aggiuntivi di Google Workspace.

   Abilita le API

2. Verifica di abilitare le API nel progetto Cloud corretto, poi fai clic su Avanti.

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

Apps Script

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

   Abilita le API

2. Verifica di abilitare le API nel progetto Cloud corretto, poi fai clic su Avanti.

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

Python

Visualizza su GitHub

Apps Script

Visualizza su GitHub

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. Sposta il file della chiave JSON credentials.json dall'account di servizio scaricato nei passaggi precedenti nella directory del progetto.

4. Nella console 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 che hai creato 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 distribuito 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 in modo che utilizzi l'agente AI ADK Travel Concierge di cui hai eseguito il deployment:

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 info_outline Panoramica e poi 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 del file Sposta file in alto.

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 AI ADK Travel Concierge di cui è stato eseguito il deployment 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 distribuito nei passaggi precedenti, PROJECT_NUMBER.

9. SERVICE_ACCOUNT_KEY con la chiave JSON dell'account di servizio scaricata 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 Cambia 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.

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 un deployment del componente aggiuntivo di Google Workspace denominato travel-concierge-addon:

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

3. Installa il deployment del componente aggiuntivo di Google Workspace:

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

Apps Script

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

1. Nel progetto Apps Script, fai clic su Deployment > Test deployment, quindi su Installa.

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, poi 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 Avatar URL (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 di 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 disponibile questa app di chat 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 deployment principale per attivare i test.

1. Nel progetto Apps Script, fai clic su Deployment > Test deployments, quindi su Copia in ID deployment principale.

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

   Vai alla pagina di configurazione dell'API Google Chat

3. Configura l'app Chat:

   1. Nel campo Nome app, inserisci Travel ADK AI Agent.
   2. Nel campo Avatar URL (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. 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.
   7. In Visibilità, seleziona Rendi disponibile questa app di chat 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.

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).

• Può verificarsi un timeout: il timeout degli aggiornamenti della barra laterale si verifica quando il completamento richiede più di qualche minuto.

Queste limitazioni non esistono in Chat.

Apps Script

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

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

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

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 attivare i documenti di Drive come funzionalità di contesto per l'applicazione Drive, in modo simile a quanto fatto con i messaggi 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 consistono nell'aggiunta del supporto per più sessioni per conversazioni separate degli utenti e altre piattaforme di gestione degli agenti AI.

• agent_handler.py: implementa le interfacce specifiche di Vertex AI definite in vertex_ai.py nei casi specifici di applicazioni Chat e non Chat. Un'estensione tipica sarebbe l'aggiunta di pulsanti per consentire agli utenti di inviare feedback sulle risposte dell'agente AI.

• google_workspace.py: implementa le interazioni della piattaforma di gestione degli agenti non AI utilizzando le chiamate API. In questo esempio vengono utilizzate solo le API Google Workspace per raccogliere i dettagli del contesto ed eseguire azioni. Un'estensione tipica consiste nell'aggiungere funzioni per recuperare i dati aziendali da Google Calendar o da un sistema di gestione dei rapporti con i clienti (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 delle risposte per visualizzare graficamente le opzioni di volo e altri agenti AI.

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à di contesto 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 interfacce specifiche di Vertex AI definite in VertexAi.gs nei casi specifici di applicazioni di chat e non di chat. Un'estensione tipica sarebbe l'aggiunta di pulsanti per consentire agli utenti di inviare feedback sulle risposte dell'agente AI.

• GoogleWorkspace.gs::implementa interazioni non AI tra la piattaforma di gestione degli agenti utilizzando chiamate API. In questo esempio vengono utilizzate solo le API Google Workspace per raccogliere i dettagli del contesto ed eseguire azioni. Un'estensione tipica consiste nell'aggiungere funzioni per recuperare i dati aziendali da Google Calendar o da un sistema di gestione dei rapporti con i clienti (CRM).

• TravelAgentUiRender.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 delle risposte per visualizzare graficamente le opzioni di volo e altri agenti AI.