Crea un'app Google Chat con un agente AI Gemini Enterprise

Questa pagina spiega come creare un componente aggiuntivo Google Workspace che funzioni in Google Chat e interagisca con un agente AI Gemini Enterprise.

Gli agenti AI percepiscono autonomamente il loro ambiente, ragionano ed eseguono azioni complesse e in più passaggi per raggiungere un obiettivo definito. In questo tutorial utilizzerai l'agente Idea Generation fornito per impostazione predefinita da Google, che aiuta gli utenti aziendali con l'innovazione e la risoluzione dei problemi.

Agente di generazione di idee 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 Gemini Enterprise.

Nel diagramma precedente, un utente che interagisce con un'app di chat implementata con un agente AI Gemini Enterprise 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 AI Gemini Enterprise 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 di Chat invia in modo asincrono le risposte 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'app Chat.
  • Configura l'app Chat.
  • Testa l'app Chat.

Prerequisiti

Configura l'ambiente

Attivare l'API Chat

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 l'API Google Chat.

Abilita l'API

Configura 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 dagli utenti e dai revisori dell'app e registra la tua 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 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 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 Discovery Engine User seguendo questi passaggi:

Google Cloud Console

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

    Vai a Service account

    I passaggi rimanenti vengono visualizzati nella console Google Cloud.

  2. Seleziona un progetto Google Cloud.
  3. Fai clic su Crea service account.
  4. Inserisci il nome di un service account da visualizzare nella console Google Cloud.
  5. Se non vuoi impostare i controlli dell'accesso, fai clic su Fine per completare la creazione del service account. Per impostare i controlli dell'accesso ora, fai clic su Crea e continua e vai al passaggio successivo.
  6. (Facoltativo) Assegna ruoli al service account per concedere l'accesso alle risorse del progetto Google Cloud oltre a quelle di Google Workspace. Per maggiori dettagli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
  7. Fai clic su Continua.
  8. (Facoltativo) Inserisci gli utenti o i gruppi che possono gestire ed eseguire azioni con questo service account. Per maggiori dettagli, consulta Simulazione dell'identità dei service account.
  9. Fai clic su Fine per completare la creazione del service account.

    Prendi nota dell'indirizzo email del service account.

gcloud CLI

  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 oltre a quelle di Google Workspace. Per maggiori dettagli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

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 al menu > IAM e amministrazione > Service account.

    Vai a Service account

    I passaggi rimanenti vengono visualizzati nella console Google Cloud.

  2. Seleziona un progetto Google Cloud.
  3. Fai clic sull'indirizzo email del service account per cui vuoi creare una chiave.
  4. Fai clic sulla scheda Chiavi.
  5. Fai clic sul menu a discesa Aggiungi chiave, quindi seleziona Crea nuova chiave.
  6. In Tipo di chiave, seleziona JSON e fai clic su Crea.

    Una nuova coppia di chiavi pubblica/privata viene generata e scaricata sul tuo computer come file della chiave del service account. Salva il file JSON scaricato come credentials.json nella directory di lavoro. Questo file è l'unica copia di questa chiave. Una volta scaricato, il file della chiave non potrà essere scaricato di nuovo. Per informazioni su come archiviare la chiave in modo sicuro, consulta Best practice per la gestione delle chiavi degli account di servizio.

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

Crea e configura il progetto dell'app Chat

  1. Nella console Google API, vai a Menu > IAM e amministrazione > Impostazioni.

    Vai a IAM e amministrazione > Impostazioni

  2. Prendi nota dei campi Numero progetto e ID progetto.

  3. Vai a Gemini Enterprise:

    Apri Gemini Enterprise

  4. Prendi nota della posizione e dell'ID dell'applicazione.

  5. Fai clic sul pulsante seguente per aprire il progetto Apps Script Avvio rapido dell'agente AI GE.

    Apri il progetto.

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

  7. Nel progetto Apps Script, fai clic su L'icona delle impostazioni del progetto Impostazioni progetto > Modifica proprietà script > Aggiungi proprietà script per aggiungere le seguenti proprietà script:

    1. REASONING_ENGINE_RESOURCE_NAME con la risorsa dell'app Gemini Enterprise composta con le informazioni indicate nei passaggi precedenti.

      projects/PROJECT_ID/locations/APP_LOCATION/collections/default_collection/engines/APP_ID

    2. SERVICE_ACCOUNT_KEY con la chiave JSON dell'account di servizio scaricata nei passaggi precedenti, ad esempio { ... }.

  8. Fai clic su Salva proprietà script.

  9. Nel progetto Apps Script, fai clic su L'icona delle impostazioni del progetto Impostazioni progetto.

  10. In Progetto Google Cloud (GCP), fai clic su Cambia progetto.

  11. In Numero di progetto Google Cloud, incolla il numero di progetto Google Cloud annotato nei passaggi precedenti.

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

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 head:

  1. Nel progetto Apps Script dell'app Chat, fai clic su Deployment > Test dei deployment.
  2. In ID deployment head, fai clic su L'icona per creare una copia 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 il test:

  1. Nella console API, 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 GE Quickstart.
    2. Nel campo URL avatar, inserisci https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
    3. Nel campo Descrizione, inserisci GE 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 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 I need to find ideas! e premienter.

    L'app Chat risponde con la risposta dell'agente Generazione di idee predefinita.

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

Risoluzione dei problemi

Quando un'app Google Chat o una scheda restituisce un errore, l'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la tua richiesta". A volte l'interfaccia utente di Chat non mostra alcun messaggio di errore, ma l'app o la scheda 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 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.

  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 quello da eliminare e fai clic su Elimina .
  3. Nella finestra di dialogo, digita l'ID progetto e fai clic su Chiudi per eliminare il progetto.