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

Anteprima per gli sviluppatori: disponibile nell'ambito del Programma Anteprima per gli sviluppatori di Google Workspace, che concede l'accesso in anteprima a determinate funzionalità.

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

Prendiamo ad esempio un'app di chat che aiuta 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?", che avvia una conversazione in stile umano con l'utente in cui l'app di Chat comprende e risponde con comandi vocali al momento della prenotazione dell'auto.

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

• Prenota voli
• Fissa un appuntamento dal medico
• Ordina cibo a domicilio
• Rispondere a domande su un catalogo di prodotti al dettaglio, ad esempio se sono disponibili in altri colori

• 

  Figura 1. Selezione di un agente predefinito per un'app Dialogflow Chat.

• 
  Figura 2. Sto testando l'agente in Dialogflow CX per verificare che la logica e la configurazione dell'agente funzionino come previsto. Il diagramma mostra un insieme sequenziale di pagine di attualità che riguardano passaggi specifici della conversazione, ad esempio l'impostazione di un luogo di prelievo e di ritorno per un'auto a noleggio, e di configurare la logica che le collega. La conversazione viene testata in un simulatore.
• 
  Figura 3. Configurare un'app di 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.
• Creare ed eseguire il deployment di un'app di chat basata sull'agente Dialogflow CX.
• Testa l'app Chat.

Prerequisiti

• Un account Google Workspace con accesso a Google Chat.
• Un progetto Google Cloud.
• Assicurati di attivare la fatturazione per il tuo progetto Cloud. Scopri come verificare lo stato di fatturazione dei tuoi progetti.

Architettura

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

Nel diagramma precedente, un utente che interagisce con un'app di 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 di Chat.
2. Un agente virtuale Dialogflow, che risiede in Google Cloud, riceve ed elabora il messaggio per produrre una risposta.
3. Facoltativamente, utilizzando un webhook Dialogflow, l'agente Dialogflow può interagire con servizi di terze parti esterni, ad esempio un sistema di gestione dei progetti o uno strumento di gestione dei ticket.
4. L'agente Dialogflow invia una risposta al servizio app Chat in Chat.
5. La risposta viene recapitata allo spazio di Chat.

Configurare l'ambiente

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.

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

   Abilita le API

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

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

Creare un agente Dialogflow CX

Un agente Dialogflow CX è un agente virtuale che gestisce le conversazioni simultanee con gli utenti finali. È 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 per le tue app e i tuoi servizi. Puoi progettare e creare 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 addestri entrambi per gestire gli scenari di conversazione previsti e la tua formazione non deve essere eccessivamente esplicita.

Ecco come creare l'agente Dialogflow CX:

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

   Vai alla console di Dialogflow CX

2. Scegli un progetto Google Cloud. Per trovare il progetto, potrebbe essere necessario fare clic su Tutti e quindi cercarlo.

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

   Per scegliere un agente predefinito, segui questi passaggi:

   1. Fai clic su Utilizza agenti predefiniti.

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

      Gli agenti vengono classificati come principiante, intermedio o avanzato 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'abilitazione di funzionalità e API nella console Google Cloud.

   3. Fai clic su Importa come agente.

   Per creare il tuo agente, segui questi passaggi:

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

   Per una procedura dettagliata dettagliata sul processo 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 località 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 cambiare la lingua predefinita di un agente dopo la creazione.

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

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

7. Come best practice, testa l'agente:

   1. Fai clic su Agente di test.
   2. Seleziona Agente di test nell'ambiente.
   3. In Ambiente, seleziona Bozza.
   4. In Flow, seleziona Default Start Flow (Avvio predefinito del flusso).
   5. Nella pagina Pagina, seleziona Pagina iniziale.
   6. Nella barra di scrittura Parla con l'agente, digita Hello e premi Invio. L'agente risponde presentandosi.
   7. Per completare il test, invia la conversazione di prova di esempio.

8. Viene creato l'agente Dialogflow CX. Torna alla console di 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, così come lo utilizzi durante la configurazione dell'app Chat.

Creare un'app di Chat e connetterla all'agente Dialogflow

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

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

   Vai all'API Chat

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

   1. In Nome 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 connessione, seleziona Dialogflow.
   6. In Impostazioni Dialogflow, seleziona Dialogflow CX.
   7. In Nome risorsa agente o ambiente, incolla il nome dell'agente Dialogflow CX che hai copiato alla fine di Crea un agente Dialogflow CX.
   8. Rendi questa app di chat disponibile a persone e gruppi specifici nel tuo dominio e inserisci il tuo indirizzo email.
   9. In Log, seleziona Registra errori 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 Dialogflow CX Chat inviando un messaggio in Google Chat.

1. Apri Google Chat utilizzando l'account Google Workspace che hai fornito quando ti sei aggiunto come trusted tester.

   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.

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

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

   L'app Dialogflow Chat risponde presentandosi.

6. Per completare il test, invia la conversazione di prova di esempio.

Esempio di conversazione di prova

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

Dialog	Spiegazione
Utente finale: Ciao Agent: Ciao. Sono l'agente virtuale di noleggio auto. Posso aiutarti a effettuare una nuova prenotazione di un noleggio auto. Come posso aiutarti oggi?	Viene chiamata la route Intent di benvenuto predefinito nel flusso di avvio predefinito. Il fulfillment per questo gestore di stato ("Ciao! Sto...") alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale:vorrei noleggiare un'auto. Agent: Dove vuoi ritirare il veicolo?	La route di intent car_rental.reservation_create nella pagina iniziale corrisponde. La sessione passa alla pagina Luogo di ritiro. Il modulo della pagina Luogo di ritiro non è completo, perciò 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 Agent: Ok, il ritiro sarà a Las Vegas. Agent: L'indirizzo di consegna è diverso da quello di ritiro?	L'input dell'utente finale compila il parametro pickup_location richiesto dall'agente nel turno precedente della conversazione. Viene trovata una corrispondenza con la route di intent car_rental.return_different_location nel flusso di avvio predefinito. Il percorso di completamento del modulo nella pagina Luogo di ritiro viene valutato e chiamato. È caratterizzato da un fulfillment ("Ok, il tuo ritiro..."), che viene aggiunto alla coda di risposta con i riferimenti ai parametri risolti con i valori effettivi forniti dall'utente finale. La sessione passa alla pagina Conferma posizione. Nella pagina Conferma posizione è presente una voce fulfillment ("La posizione di consegna è diversa..."), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale:sì. Lascerò l'auto a Los Angeles. Agente: Ok, la consegna sarà a Los Angeles. Agent: Che data e ora vuoi ritirare il veicolo?	Viene trovata una corrispondenza con la route di intent car_rental.return_different_location nel flusso di avvio predefinito. La sessione passa alla pagina Abbandono località. L'input dell'utente finale compila il parametro drop_off_location richiesto dall'agente nel turno precedente della conversazione. Il percorso di completamento del modulo nella pagina Posizione di abbandono viene valutata e chiamata. Include un fulfillment ("Ok, l'abbandono..."), che viene aggiunto alla coda di risposta. La sessione passa alla pagina Durata noleggio. Nella pagina Durata del noleggio i valori del modulo sono incompleti, pertanto all'utente viene richiesto di specificare il parametro pickup_date_time ("La data e l'ora di ritiro..."), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale:voglio ritirare l'auto il 5 marzo a mezzogiorno. Agente: a che ora e a che data vuoi lasciare il veicolo?	L'input dell'utente finale compila il parametro pickup_date_time richiesto dall'agente nel turno precedente della conversazione. Nella pagina Durata del noleggio manca un altro valore del modulo, pertanto chiede all'utente il parametro drop_off_date_time ("La data e l'ora di interruzione..."), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale:15 marzo a mezzogiorno. Agente: Quindi, per conferma: Prendererai il veicolo a Las Vegas 05/03/2024 12:00:00 e lo rilascerai a Los Angeles 15/03/2024 12:00:00 Va bene?	L'input dell'utente finale compila il parametro drop_off_date_time richiesto dall'agente nel turno precedente della conversazione. La sessione passa alla pagina Conferma durata noleggio. Nella pagina Conferma durata noleggio è presente una voce evasa ("Quindi, per confermare..."), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale:Sì, grazie. Agent: Ottimo. Ora scegliamo un veicolo. Agent: Vuole un veicolo economico o di lusso?	La route dell'intent small_talk.confirmation.yes nella pagina Conferma durata noleggio corrisponde. L'agente conferma la scelta dell'utente con un messaggio ("Ottimo! Ora scegliamo..."), che viene aggiunto alla coda di risposta. La sessione passa alla pagina Disambiguazione del veicolo. Il modulo della pagina Disambiguazione del veicolo non è completo, pertanto l'agente utilizza il parametro vehicle_type per chiedere all'utente ("Vuoi un'economia o un lusso..."), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale:economia, grazie. Agente: Vuole l'auto Cymbal o il furgone di Cymbal?	La route di intent $session.params.vehicle_type="economy_vehicle" corrisponde. La sessione passa alla pagina Opzioni economiche. Nella pagina Opzioni economiche è presente un fulfillment di voci ("Ti piace il..."), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale.
Utente finale:Cymbal Trailer. Agent: Il camion Cymbal costa 50,33 $al giorno. Può ospitare fino a 4 persone ed è dotata di radio AM/FM. Vuoi procedere con il pagamento? Utente finale: sì, grazie.	La route per l'intent $session.params.vehicle_type="Cymbal Trailer" viene soddisfatta e il parametro vehicle_model viene compilato. La sessione passa alla pagina Conferma camion di Cymbal. La pagina Confirm Cymbal Trailer (Conferma veicolo di Cymbal) ha un fulfillment ("Il camion di Cymbal 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 alla route small_talk.confirmation.yes.
Agent: Che tipo di carta intendi utilizzare? Utente finale: Altostrat Agent: Inserisci il numero della carta. Utente finale: 1234 1234 1234 1234 Agent: Qual è il nome riportato sulla carta? Utente finale: Carlo Agent: Qual è l'indirizzo di fatturazione? Utente finale: 1800 Amphibious Blvd. Mountain View, CA Agente: Qual è il codice postale di fatturazione? Utente finale: 94045 Agent: Preleverai l'auto Cymbal a Las Vegas, 05/03/2024 12:00:00, e la ritirerai, 15/03/2024 12:00:00. Il totale per questo viaggio sarà di $ 175,38. Agente: Grazie per aver noleggiato con noi. Buona giornata.	La sessione passa alla pagina Pagamento. Poiché il modulo Pagamento non è completo, l'agente richiede all'utente i parametri card_type, card_number, billing_name, billing_street_address e billing_zip_code ("Quale tipo di carta verrà..."), che vengono aggiunti in sequenza alla coda di risposta e inviati quando l'utente risponde. Le risposte dell'utente impostano ogni valore parametro. La sessione passa alla pagina Conferma noleggio. Nella pagina Conferma noleggio è presente una voce in cui si evade ("Ok, il ritiro verrà..."), che viene aggiunto alla coda di risposta. L'agente invia la coda di risposta all'utente finale. La sessione viene trasferita alla pagina End Session (Fine sessione).

Inviare messaggi delle schede da Dialogflow

Dialogflow può rispondere con messaggi di SMS o schede. Per rispondere con un messaggio della carta, specificalo come payload personalizzato in fulfillment.

Il seguente JSON mostra come inviare un messaggio della carta come payload personalizzato in fulfillment:

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
  • L'input della query inviato all'agente Dialogflow corrisponde al valore del campo argumentText nel messaggio di Chat. Se il messaggio include un comando slash, viene utilizzato il valore del campo text.
  • Il payload JSON completo di ogni evento di interazione con Chat viene inviato a Dialogflow come payload personalizzato nel parametro di query ed è accessibile con un webhook Dialogflow eseguendo una query sul valore del campo WebhookRequest.payload.
• I comandi slash hanno un supporto limitato:
  • I comandi con barra che aprono le finestre di dialogo non sono supportati dalle app Dialogflow Chat.
  • Quando le app di 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 al fine di rilevare il comando slash.
  • Se l'agente Dialogflow deve elaborare il payload JSON dell'evento di interazione Chat del comando slash, può farlo utilizzando un webhook Dialogflow per esaminare il payload personalizzato nel parametro di query.
• Le anteprime link non sono supportate.
• Se l'agente Dialogflow risponde con un solo messaggio, questo viene inviato a Google Chat in modo sincrono. Se l'agente Dialogflow risponde con più messaggi, tutti i messaggi vengono inviati a Chat in modo asincrono chiamando il metodo create nella risorsa spaces.messages nell'API Chat una volta per ogni messaggio.

Risolvi il problema

Quando un'app o una scheda Google Chat restituisce un errore, nell'interfaccia di Chat viene visualizzato il messaggio "Si è verificato un problema" o "Impossibile elaborare la richiesta". A volte nell'interfaccia utente di Chat non vengono visualizzati messaggi di errore, ma l'app o la scheda Chat produce un risultato imprevisto; ad esempio, è possibile che non venga visualizzato un messaggio di scheda.

Anche se 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 di Chat è attivata. Per informazioni su visualizzazione, debug e correzione degli errori, consulta l'articolo 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 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 progetto, ad esempio un URL su appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se prevedi di esplorare più tutorial e guide rapide, puoi riutilizzare i progetti per evitare 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 quello da eliminare e fai clic su Elimina .
3. Nella finestra di dialogo, digita l'ID progetto e fai clic su Arresta per eliminare il progetto.

Argomenti correlati

• Dialogflow CX adotta un approccio a macchina di stato alla progettazione degli agenti Dialogflow, che offre un controllo chiaro ed esplicito su una conversazione, una migliore esperienza per l'utente finale e un migliore flusso di lavoro di sviluppo. 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 dettagliata su come creare e configurare gli agenti, consulta Creare un agente Dialogflow CX.
• Dialogflow ES è un altro modo per utilizzare Dialogflow con un'app di chat.