Crea un'app Google Chat con un agente AI ADK

Questa pagina spiega come creare un componente aggiuntivo di Google Workspace che funziona in Google Chat e si interfaccia con un agente AI dell'Agent Development Kit (ADK) ospitato in Vertex AI Agent Engine.

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

Esempio multi-agente di LLM Auditor come app di chat.

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

Architettura di un'app di chat implementata con un agente AI ADK.

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

  1. Un utente invia un messaggio a un'app di Chat, tramite 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 AI implementato con ADK e ospitato con Vertex AI Agent Engine riceve ed elabora l'interazione.
  4. Se vuoi, l'app di Chat o l'agente AI può integrarsi con i servizi Google Workspace, come Calendar o Fogli, o con altri servizi Google, come Google Maps o YouTube.
  5. L'app di Chat invia in modo asincrono le risposte 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 AI ADK.
  • Eseguire il deployment dell'app di Chat.
  • Configurare l'app di Chat.
  • Testare l'app di Chat.

Prerequisiti

Configurare l'ambiente

Abilitare le API Cloud di Google

Prima di utilizzare le API di 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 mostrato agli utenti e ai revisori dell'app e registra l'app in modo che tu possa pubblicarla in un secondo momento.

  1. Nella console API di Google, vai a Menu > Piattaforma Google Auth > Branding.

    Vai a Branding

  2. Se hai già configurato la piattaforma Google Auth, puoi configurare le seguenti impostazioni della schermata per il consenso OAuth in Branding, Pubblico e Accesso ai dati. Se visualizzi 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 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 di 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 API di Google

  1. Nella console API di Google, 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 dell'account di servizio, quindi fai clic su Crea e continua.
  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 service account. 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 dei service account.

Crea una chiave privata

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ù sui service account, consulta la documentazione sui service account in Google Cloud IAM .

Eseguire il deployment dell'agente AI ADK

  1. Apri l'esempio di LLM Auditor in Vertex AI Agent Garden:

    Apri l'esempio

  2. Fai clic su Esegui il deployment.

  3. Se richiesto, seleziona il tuo progetto Google Cloud.

  4. Fai clic su Esegui il deployment in Cloud Shell.

  5. Se richiesto, fai clic su Autorizza e segui il flusso OAuth per Cloud Shell.

  6. Quando Cloud Shell è completamente caricato, premi Invio per eseguire la riga di comando precaricata e avviare il deployment.

  7. Se ti viene chiesto di inserire la regione, premi Invio per utilizzare quella predefinita.

  8. Al termine, vai a Vertex AI Agent Engine:

    Apri Vertex AI Agent Engine

  9. Fai clic su L'icona per creare una copia per copiare il nome della risorsa dell'agente di cui è stato appena eseguito il deployment dalla tabella.

Creare e configurare il progetto dell'app di Chat

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

    Apri il progetto

  2. Fai clic su Panoramica > L'icona per creare una copia Crea una copia.

  3. Nel progetto Apps Script, fai clic su L'icona delle impostazioni progetto 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 del service account scaricata nei passaggi precedenti, ad esempio { ... }.

  4. Fai clic su Salva proprietà script.

  5. Nella console API di Google, 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 L'icona delle impostazioni progetto Impostazioni progetto.

  8. In Progetto Google Cloud, fai clic su Cambia 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 head:

  1. Nel progetto Apps Script dell'app di Chat, fai clic su Esegui il deployment > Deployment di test.
  2. In ID deployment head, fai clic su L'icona per creare una copia 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 API, 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 ADK Quickstart.
    2. Nel campo URL avatar, inserisci https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
    3. Nel campo Descrizione, inserisci ADK 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 head 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.

  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 sub-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 Google Chat.

Risoluzione dei problemi

Quando un'app o scheda di Google Chat restituisce un errore, l' interfaccia di Chat mostra il messaggio "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 nell'interfaccia utente di Chat potrebbe non essere visualizzato un messaggio di errore, 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.

Libera spazio

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 API di Google, 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.