Crea un'app Google Chat Dialogflow CX che capisce e risponde con il linguaggio naturale

Questa pagina spiega come creare un'app Google Chat in grado di comprendere e rispondere con linguaggio naturale utilizzando Dialogflow. Questa guida utilizza Dialogflow CX, che ha un'integrazione diretta con Google Chat. Puoi anche utilizzare Dialogflow ES per creare un'app Dialogflow ES Google Chat seguendo la guida su Dialogflow ES Google Chat.

Ad esempio, prendi in considerazione un'app di chat che aiuta le persone a noleggiare auto. Un utente potrebbe scrivere "Vorrei noleggiare un'auto". L'app Chat potrebbe rispondere con una domanda come "Dove vuoi ritirare il veicolo?", avviando una conversazione simile a quella con una persona con l'utente, in cui l'app Chat comprende e risponde con un linguaggio umano durante la prenotazione dell'auto a noleggio.

Questo è solo un esempio. Le app di chat Dialogflow sono utili in tutti i tipi di interazioni. Se richiede un linguaggio umano naturale, richiede un'app Dialogflow Chat. Gli agenti predefiniti ti aiutano a iniziare rapidamente e a mostrare cosa può fare Dialogflow, ad esempio:

• Prenotare voli
• Fissare appuntamenti dal medico
• Ordinare cibo a domicilio
• Rispondere a domande su un catalogo di prodotti di vendita al dettaglio, ad esempio se gli articoli sono disponibili in altri colori

• 

  Figura 1. Seleziona un agente predefinito per un'app Dialogflow Chat.

• 
  Figura 2. Testare l'agente in Dialogflow CX per assicurarsi che la logica e la configurazione dell'agente funzionino come previsto. Il diagramma mostra un insieme sequenziale di pagine tematiche che riguardano passaggi specifici della conversazione, come l'impostazione di una località di ritiro e restituzione di un'auto a noleggio, e configura la logica che le collega. La conversazione viene testata in un simulatore.
• 
  Figura 3. Configurazione di un'app Chat per elaborare le risposte utilizzando l'agente Dialogflow CX nella pagina di configurazione dell'API Chat nella console Google Cloud.
• 
  Figura 4. Conversazione sulla prenotazione di un'auto a noleggio con l'app Dialogflow Chat in Google Chat.

Obiettivi

• Configurare l'ambiente.
• Crea ed esegui il deployment di un agente Dialogflow CX.
• Crea ed esegui il deployment di un'app di chat basata sull'agente Dialogflow CX.
• 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 attivata per un progetto esistente, consulta Verificare lo stato della fatturazione dei progetti. Per creare un progetto e configurare la fatturazione, consulta Creare un progetto Google Cloud.

Architettura

Il seguente diagramma mostra l'architettura di un'app di chat creata con Dialogflow:

Nel diagramma precedente, un utente che interagisce con un'app Dialogflow Chat ha il seguente flusso di informazioni:

1. Un utente invia un messaggio in Chat a un'app Chat, in un messaggio diretto o in uno spazio Chat.
2. Un agente virtuale Dialogflow, che si trova in Google Cloud, riceve e elabora il messaggio per produrre una risposta.
3. Se vuoi, puoi utilizzare un webhook Dialogflow per consentire all'agente Dialogflow di interagire con servizi esterni di terze parti, come un sistema di gestione dei progetti o uno strumento per la creazione di ticket.
4. L'agente Dialogflow invia una risposta al servizio dell'app Chat in Chat.
5. La risposta viene inviata allo spazio di Chat.

Configurare l'ambiente

Prima di utilizzare le API Google, devi attivarle in un progetto Google Cloud. Puoi attivare una o più API in un singolo progetto Google Cloud.

1. Nella console Google Cloud, abilita l'API Google Chat e l'API Dialogflow.

   Abilita le API

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

3. Verifica di attivare le API corrette, quindi fai clic su Attiva.

Creare un agente Dialogflow CX

Un agente Dialogflow CX è un agente virtuale che gestisce conversazioni simultanee con gli utenti finali. Si tratta di un modulo di comprensione del linguaggio naturale che comprende le sfumature del linguaggio umano. Dialogflow traduce il testo dell'utente finale durante una conversazione in dati strutturati comprensibili dalle tue app e dai tuoi servizi. Progetta e crea un agente Dialogflow per gestire i tipi di conversazioni richiesti per il tuo sistema.

Un agente Dialogflow è come un agente di call center umano. Li addestrini entrambi per gestire gli scenari di conversazione previsti e l'addestramento non deve essere esageratamente esplicito.

Ecco come creare l'agente Dialogflow CX:

1. Nella console Dialogflow CX, apri la console Dialogflow CX. Fai clic su Menu > Dialogflow CX.

   Vai alla console di Dialogflow CX

2. Scegli un progetto Google Cloud. Per trovare il progetto, potresti dover fare clic su Tutti e poi cercarlo.

3. Ora hai la possibilità di scegliere un agente predefinito o crearne uno personalizzato. Se preferisci esplorare la personalizzazione degli agenti in dettaglio in un secondo momento, scegli uno degli agenti predefiniti, che sono utili anche per scoprire cosa possono fare gli agenti.

   Per scegliere un agente predefinito:

   1. Fai clic su Utilizza agenti predefiniti.

   2. Seleziona un agente predefinito. Per questa guida, seleziona Viaggi: noleggio auto.

      Gli agenti vengono classificati come principianti, intermediari o avanzati in base al numero di funzionalità utilizzate e alla complessità della logica di conversazione. La scelta di un agente intermedio o avanzato potrebbe richiedere personalizzazioni e impostazioni specifiche dell'agente, inclusa l'attivazione di funzionalità e API nella console Google Cloud.

   3. Fai clic su Importa come agente.

   Per creare il tuo agente:

   1. Fai clic su Crea agente.
   2. Seleziona Genera automaticamente per creare un agente del datastore o Crea il tuo per creare altri tipi di agenti.

   Per una procedura dettagliata della procedura di creazione dell'agente, consulta Creare un agente Dialogflow CX.

4. Configura le impostazioni di base dell'agente:

   1. In Nome visualizzato, inserisci un nome visualizzato.
   2. Seleziona la tua posizione preferita. Se vuoi modificare le impostazioni di geolocalizzazione avanzate, fai clic su Modifica.
   3. Seleziona il fuso orario che preferisci.
   4. Seleziona la lingua predefinita per l'agente. Non puoi modificare la lingua predefinita di un agente dopo la creazione.

5. Fai clic su Crea. Dialogflow CX inizia a creare l'agente e poi visualizza il flusso di inizio predefinito dell'agente.

6. Se vuoi, personalizza l'agente. Per una procedura dettagliata sulla procedura di personalizzazione dell'agente, consulta Creare un agente Dialogflow CX.

7. Come best practice, testa l'agente:

   1. Fai clic su Testa agente.
   2. Seleziona Testa l'agente nell'ambiente.
   3. In Ambiente, seleziona Bozza.
   4. In Flusso, seleziona Flusso di inizio predefinito.
   5. In Pagina, seleziona Pagina iniziale.
   6. Nella barra di composizione Parla con un agente, digita Hello e premi Invio. L'agente risponde presentandosi.
   7. Completa il test con la conversazione di test di esempio.

8. L'agente Dialogflow CX viene creato. Torna alla console Dialogflow CX. Fai clic su Menu > Dialogflow CX.

   Vai alla console di Dialogflow CX

9. In Agenti, fai clic su > Copia nome. Salva questo nome, poiché lo utilizzerai durante la configurazione dell'app Chat.

Crea un'app di chat e connettila all'agente Dialogflow

Dopo aver creato un agente Dialogflow CX, segui questi passaggi per trasformarlo in un'app di chat:

1. Nella console Google Cloud, vai all'API Google Chat. Cerca "API Google Chat", fai clic su API Google Chat e poi su Gestisci.

   Vai all'API Chat

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

   1. In Nome dell'app, inserisci Dialogflow App.
   2. In URL avatar, inserisci https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png.
   3. In Descrizione, inserisci Responds to real human conversation.
   4. In Funzionalità, seleziona Ricevi messaggi 1:1 e Partecipa a spazi e conversazioni di gruppo.
   5. In Impostazioni di connessione, seleziona Dialogflow.
   6. In Impostazioni Dialogflow, seleziona Dialogflow CX.
   7. In Nome risorsa dell'agente o dell'ambiente, incolla il nome dell'agente Dialogflow CX che hai copiato alla fine di Creare un agente Dialogflow CX.
   8. Rendi disponibile l'app di chat a utenti e gruppi specifici nel tuo dominio e inserisci il tuo indirizzo email.
   9. In Log, seleziona Errori di log in Logging.

3. Fai clic su Salva.

L'app Chat è pronta per ricevere e rispondere ai messaggi su Chat.

Testare l'app Chat

Testa l'app di chat Dialogflow CX inviando un messaggio in Google Chat.

1. Apri Google Chat utilizzando l'account Google Workspace fornito quando hai aggiunto te stesso come tester attendibile.

   Vai a Google Chat

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

4. Seleziona l'app Chat dai risultati. Viene visualizzato un messaggio diretto.

   Nota: se non vedi la tua app di Chat nell'elenco dei risultati, assicurati di aver incluso il tuo account Google Workspace nelle impostazioni Visibilità della pagina Configurazione dell'API Chat nella console Google Cloud.

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

   L'app Dialogflow Chat risponde presentandosi.

6. Completa il test con la conversazione di test di esempio.

Conversazione di test di esempio

Per testare l'app Chat di Dialogflow CX nella console Dialogflow CX o in Google Chat, svolgi la seguente conversazione. La spiegazione ti aiuta a capire in che modo l'agente Dialogflow CX interpreta il linguaggio naturale dell'utente e produce la propria risposta in linguaggio naturale in ogni passaggio della conversazione. Questa conversazione di esempio si basa sull'agente predefinito chiamato Viaggi: noleggio auto.

Dialog	Spiegazione
Utente finale: Ciao. Agente: Ciao. Sono l\'agente virtuale per il noleggio auto. Posso aiutarti a iniziare una nuova prenotazione di auto a noleggio. Come posso aiutarti oggi?	Viene chiamato il percorso Intent di benvenuto predefinito nel Flusso di inizio predefinito. L'implementazione di questo gestore dello stato ("Un saluto da Google. Sono…") viene aggiunta alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale: vorrei noleggiare un'auto. Agente: dove vuoi ritirare il veicolo?	Il percorso dell'intent car_rental.reservation_create nella home page è associato. La sessione passa alla pagina Posizione di ritiro. Il modulo della pagina Pickup Location (Posizione di ritiro) non è completo, pertanto l'agente utilizza il parametro pickup_location per chiedere all'utente ("Dove vuoi ritirare…"), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale: Las Vegas Agente: OK, il ritiro avverrà a Las Vegas. Agente: la località di consegna è diversa da quella di ritiro?	L'input dell'utente finale completa il parametro pickup_location richiesto dall'agente nel turno di conversazione precedente. Il percorso dell'intent car_rental.return_different_location nel Flusso di inizio predefinito è associato. Il percorso di compilazione del modulo nella pagina Pickup Location (Località di ritiro) viene valutato e chiamato. Ha un completamento ("Ok, il ritiro…"), che viene aggiunto alla coda di risposta con i riferimenti dei parametri risolti in valori effettivi forniti dall'utente finale. La sessione passa alla pagina Conferma posizione. La pagina Conferma posizione contiene un campo per l'inserimento di un'informazione ("La località di consegna è diversa…"), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale: sì. Rilascerò l'auto a Los Angeles. Agente: OK, la consegna sarà a Los Angeles. Agente: a che data e a che ora vuoi ritirare il veicolo?	Il percorso dell'intent car_rental.return_different_location nel Flusso di inizio predefinito è associato. La sessione passa alla pagina Località di consegna. L'input dell'utente finale compila il parametro drop_off_location richiesto dall'agente nel turno di conversazione precedente. Il percorso di compilazione del modulo nella pagina Posizione di consegna viene valutato e chiamato. Ha un completamento ("Ok, il tuo ritiro…"), che viene aggiunto alla coda di risposta. La sessione passa alla pagina Rental Duration (Durata noleggio). La pagina Durata del noleggio contiene valori di modulo incompleti, pertanto viene richiesto all'utente il parametro pickup_date_time ("Quale data e ora vuoi ritirare il veicolo…"), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale: vorrei ritirare l'auto il 5 marzo a mezzogiorno. Agente: a che data e a che ora vuoi restituire il veicolo?	L'input dell'utente finale completa il parametro pickup_date_time richiesto dall'agente nel turno di conversazione precedente. La pagina Durata del noleggio presenta un altro valore del modulo mancante, pertanto chiede all'utente il parametro drop_off_date_time ("In che data e orario vuoi restituire il veicolo…"), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale: 15 marzo a mezzogiorno. Agente: per conferma: Ritirarai il veicolo a Las Vegas il 05/03/2024 alle 12:00:00 e lo restituirai a Los Angeles il 15/03/2024 alle 12:00:00 Giusto?	L'input dell'utente finale completa il parametro drop_off_date_time richiesto dall'agente nel turno di conversazione precedente. La sessione passa alla pagina Conferma durata noleggio. La pagina Conferma la durata del noleggio contiene un completamento dell'inserimento ("Per conferma…"), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale: Sì, grazie. Agente: Ottimo. Ora scegli un veicolo. Agente: preferisci un veicolo economico o di lusso?	Il percorso dell'intent small_talk.confirmation.yes nella pagina Conferma durata del noleggio è associato. L'agente conferma la scelta dell'utente con un messaggio ("Ottimo! Ora scegli…"), che viene aggiunto alla coda di risposta. La sessione passa alla pagina Disambiguazione del veicolo. Il modulo della pagina Disambiguazione veicolo non è completo, pertanto l'agente utilizza il parametro vehicle_type per chiedere all'utente ("Ti piacerebbe un'auto economica o di lusso…"), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale: economica. Agente: preferisci l'auto Cymbal o il camion Cymbal?	Il percorso dell'intente $session.params.vehicle_type="economy_vehicle" è associato. La sessione passa alla pagina Opzioni economiche. La pagina Opzioni economiche contiene un'opzione di completamento della richiesta ("Vuoi…"), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale: Cymbal Truck. Agente: il camion Cymbal costa 50,33 $al giorno. Può ospitare 4 persone ed è dotata di una radio AM/FM. Vuoi procedere al pagamento? Utente finale: sì.	Il percorso dell'intente $session.params.vehicle_type="Cymbal Truck" viene trovato e il parametro vehicle_model viene compilato. La sessione passa alla pagina Conferma camion per piatti. La pagina Conferma Cymbal Truck contiene un completamento di voce ("Il Cymbal Truck costa 50,33 $al giorno…"), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale. La risposta dell'utente corrisponde al percorso small_talk.confirmation.yes.
Agente: che tipo di carta utilizzerai? Utente finale: Altostrat Agente: inserisci il numero della carta. Utente finale: 1234 1234 1234 1234 Agente: qual è il nome sulla carta? Utente finale: Charlie Agente: qual è l'indirizzo di fatturazione? Utente finale: 1800 Amphibious Blvd. Mountain View, CA Agente: qual è il codice postale di fatturazione? Utente finale: 94045 Agente: ritirerai l'auto Cymbal a Las Vegas il 05-03-2024 alle ore 12:00:00 e la ricondurrai il 15-03-2024 alle ore 12:00:00. Il totale per questo viaggio sarà di 175,38 $. Agente: grazie per aver scelto di affittare con noi. Buona giornata.	La sessione passa alla pagina Pagamento. Il modulo Pagamento non è completo, quindi l'agente chiede all'utente i parametri card_type, card_number, billing_name, billing_street_address e billing_zip_code ("Che tipo di carta..."), che vengono aggiunti in sequenza alla coda di risposta e inviati man mano che l'utente risponde. Le risposte dell'utente impostano ogni valore del parametro. La sessione passa alla pagina Conferma noleggio. La pagina Conferma di noleggio contiene un completamento di voce ("Ok, il ritiro sarà…"), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale. La sessione passa alla pagina Termina sessione.

Inviare messaggi della scheda da Dialogflow

Codelab: per un esempio pratico di invio di messaggi con schede da Dialogflow, consulta Mostrare le origini nelle risposte dell'app di conoscenza Chat nel codelab Crea app per Google Chat con Gemini.

Dialogflow può rispondere con messaggi di testo o di scheda. Per rispondere con un messaggio della scheda, specificalo come payload personalizzato nel compimento.

Il seguente JSON mostra come inviare un messaggio della scheda come payload personalizzato nel completamento:

json

{
  'cardsV2': [{
    'cardId': 'createCardMessage',
    'card': {
      'header': {
        'title': 'A card message!',
        'subtitle': 'Sent from Dialogflow',
        'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
        'imageType': 'CIRCLE'
      },
      'sections': [
        {
          'widgets': [
            {
              'buttonList': {
                'buttons': [
                  {
                    'text': 'Read the docs!',
                    'onClick': {
                      'openLink': {
                        'url': 'https://developers.google.com/workspace/chat'
                      }
                    }
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }]
}

Limiti e considerazioni

• Gli eventi di interazione con la chat hanno un supporto limitato e alcune considerazioni:
  • Sono supportati i seguenti tipi di eventi di interazione:
    • MESSAGE
    • ADDED_TO_SPACE
    • CARD_CLICKED
  • Per gli eventi MESSAGE o ADDED_TO_SPACE, l'input della query inviato all'agente Dialogflow corrisponde al valore del campo argumentText nel messaggio di Chat. Se il messaggio include un comando barra, viene utilizzato il valore del campo text.
  • Per gli eventi CARD_CLICKED, l'input della query inviato all'agente Dialogflow è formattato come CARD_CLICKED.functionName, dove functionName corrisponde al valore del campo function dell'oggetto Azione associato all'elemento della scheda interattiva (ad esempio un pulsante).
  • Il payload JSON completo di ogni evento di interazione con la chat viene inviato a Dialogflow come payload personalizzato nel parametro di query e può essere accessibile con un webhook Dialogflow eseguendo una query sul valore del campo WebhookRequest.payload.
• Considerazioni per rispondere ai comandi slash e ricevere dati da schede o finestre di dialogo:
  • Quando le app Dialogflow Chat ricevono un messaggio con un comando slash, l'input della query contiene solo il valore del campo text. Il campo text inizia con il nome del comando slash (ad esempio, /command), che puoi utilizzare per configurare l'intent di un agente Dialogflow per rilevare un comando slash.
  • Se l'agente Dialogflow deve elaborare il payload JSON dell'evento di interazione con la chat, puoi farlo utilizzando un webhook Dialogflow per ispezionare il payload personalizzato nel parametro di query.
  • Per visualizzare una dialogo dall'agente Dialogflow, rispondi con un singolo payload JSON personalizzato che includa un messaggio contenente una DIALOG risposta all'azione.
  • Per elaborare i dati inseriti dalle schede, l'agente Dialogflow può rilevare gli intent che iniziano con il testo CARD_CLICKED e rispondere con un singolo payload JSON personalizzato contenente l'azione appropriata.
• Le anteprime dei link non sono supportate.
• Se l'agente Dialogflow risponde con un solo messaggio, questo viene inviato in modo sincrono a Google Chat. Se l'agente Dialogflow risponde con più messaggi, tutti i messaggi vengono inviati a Chat in modo asincrono chiamando il metodo create sulla risorsa spaces.messages nell'API Chat una volta per ogni messaggio.
• Quando utilizzi l'integrazione di Dialogflow CX con Chat, l'agente Dialogflow e l'app Chat devono essere configurati nello stesso progetto Google Cloud. Se devi configurare Dialogflow e Chat in progetti Cloud diversi, puoi configurare un server intermedio per semplificare la connessione. Per scoprire come, consulta questo esempio di integrazione di chat per Dialogflow CX su GitHub.

Risoluzione dei problemi

Quando un'app o una scheda di Google Chat 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 Chat o la scheda produce un risultato imprevisto; ad esempio, un messaggio della scheda potrebbe non essere visualizzato.

Sebbene un messaggio di errore potrebbe non essere visualizzato nell'interfaccia utente di Chat, sono disponibili messaggi di errore descrittivi e dati di log per aiutarti a correggere gli errori quando la registrazione degli errori per le app Chat è attivata. Per assistenza su come visualizzare, eseguire il debug e correggere gli errori, consulta la sezione 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.

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, quando lo elimini elimini anche tutto il lavoro effettuato 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 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 Google Cloud, 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 e fai clic su Elimina .
3. Nella finestra di dialogo, digita l'ID progetto e fai clic su Chiudi per eliminare il progetto.

Argomenti correlati

• Dialogflow CX adotta un approccio basato su macchine a stati per la progettazione degli agenti Dialogflow, che offre un controllo chiaro ed esplicito su una conversazione, un'esperienza utente finale migliore e un flusso di lavoro di sviluppo migliore. Quando crei un'app Dialogflow Chat, ti consigliamo di utilizzare Dialogflow CX.
  • Per scoprire di più sulla creazione e sulla configurazione degli agenti, consulta Agenti Dialogflow CX.
  • Per una procedura dettagliata su come creare e configurare gli agenti, consulta Creare un agente Dialogflow CX.
  • Codelab: per un esempio di come creare un agente del datastore Dialogflow CX, consulta l'app di Chat della conoscenza del codelab Crea app per Google Chat con Gemini.
  • Codelab: per un esempio di come creare un agente conversazionale Dialogflow CX, consulta l'app di feedback Chat del codelab Creare app per Google Chat con Gemini.
• Dialogflow ES è un altro modo per utilizzare Dialogflow con un'app di chat.