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 un 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 Google Chat Dialogflow ES seguendo la guida Google Chat Dialogflow ES.

Ad esempio, considera un'app 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?", che avvia una conversazione con l'utente in cui l'app Chat comprende e risponde con un linguaggio umano durante la prenotazione del noleggio auto.

Questo è solo un esempio. Le app di chat Dialogflow sono utili in tutti i tipi di interazioni. Se richiede un linguaggio umano naturale, è necessaria un'app Dialogflow Chat. Gli agenti predefiniti ti aiutano a iniziare rapidamente e mostrano le funzionalità di Dialogflow, ad esempio:

• Prenota voli
• Pianificare 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. Selezione di un agente predefinito per un'app di chat Dialogflow.

• 
  Figura 2. Test dell'agente in Dialogflow CX per assicurarsi che la logica e la configurazione dell'agente funzionino come previsto. Il diagramma mostra una serie sequenziale di pagine tematiche che riguardano passaggi specifici della conversazione, come l'impostazione di una località di ritiro e riconsegna per 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. Avere una conversazione sulla prenotazione di un'auto a noleggio con l'app Dialogflow Chat in Google Chat.

Obiettivi

• Configurare l'ambiente.
• Crea e implementa un agente Dialogflow CX.
• Crea e implementa 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 di 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 di chat Dialogflow ha il seguente flusso di informazioni:

1. Un utente invia un messaggio in Chat a un'app di Chat, in un messaggio diretto o in uno spazio di Chat.
2. Un agente virtuale Dialogflow, che si trova in Google Cloud, riceve ed elabora il messaggio per produrre una risposta.
3. Se vuoi, utilizzando un webhook Dialogflow, l'agente Dialogflow può interagire con servizi esterni di terze parti, ad esempio un sistema di gestione dei progetti o uno strumento di gestione dei 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 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, poi fai clic su Avanti.

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

Crea 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. Progetti e crei un agente Dialogflow per gestire i tipi di conversazioni richiesti per il tuo sistema.

Un agente Dialogflow è come un operatore umano di un call center. Li addestri entrambi a gestire gli scenari di conversazione previsti e l'addestramento non deve essere eccessivamente 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 tuo progetto, potresti dover fare clic su Tutti e poi cercarlo.

3. Ora puoi scegliere un agente predefinito o crearne uno personalizzato. Se preferisci esplorare in dettaglio la personalizzazione degli agenti 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, intermedi o avanzati in base al numero di funzionalità utilizzate e alla sofisticazione della logica di conversazione. La scelta di un agente intermedio o avanzato potrebbe richiedere personalizzazioni e impostazioni specifiche dell'agente, tra cui 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 datastore o seleziona Crea il tuo per creare altri tipi di agenti.

   Per una procedura dettagliata del 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 tua posizione preferita. Se vuoi modificare le impostazioni di localizzazione 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 mostra il flusso di avvio predefinito dell'agente.

6. (Facoltativo) Personalizza l'agente. Per una procedura dettagliata per la personalizzazione dell'agente, vedi 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 Flow, seleziona Default Start Flow.
   5. In Pagina, seleziona Pagina iniziale.
   6. Nella barra di composizione Parla con un operatore, 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, in quanto lo utilizzerai quando configuri l'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" e fai clic su API Google Chat, poi 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 Partecipa a spazi e conversazioni di gruppo.
   5. Nella sezione Impostazioni di connessione, seleziona Dialogflow.
   6. In Impostazioni di 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 Crea un agente Dialogflow CX.
   8. Rendi disponibile questa app di chat a persone 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 a ricevere e rispondere ai messaggi su Chat.

Testare l'app Chat

Prova l'app Chat Dialogflow CX inviando un messaggio in Google Chat.

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

4. Seleziona l'app di chat dai risultati. Si apre 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 di visibilità della pagina di 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. Completa il test con la conversazione di test di esempio.

Conversazione di prova di esempio

Per testare l'app Dialogflow CX Chat nella console Dialogflow CX o in Google Chat, segui questa conversazione. La spiegazione ti aiuta a capire come l'agente di 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 ad avviare una nuova prenotazione di noleggio auto. Come posso aiutarti oggi?	Viene chiamato il percorso Intent di benvenuto predefinito nel Flusso di avvio predefinito. L'intent per questo gestore di stati ("Hi! Sono…") viene aggiunto alla coda delle risposte. L'agente invia la coda di risposte all'utente finale.
Utente finale: vorrei noleggiare un'auto. Agente: Dove vorresti ritirare il veicolo?	Viene abbinato l'intent car_rental.reservation_create nella pagina iniziale. La sessione passa alla pagina Luogo di ritiro. Il modulo della pagina Luogo di ritiro non è completo, quindi l'agente utilizza il parametro pickup_location per chiedere all'utente ("Dove vorresti ritirare…"). che viene aggiunto alla coda delle risposte. L'agente invia la coda di risposte all'utente finale.
Utente finale: Las Vegas Agente: Ok, il ritiro avverrà a Las Vegas. Agente:la località di riconsegna è diversa da quella di ritiro?	L'input dell'utente finale compila il parametro pickup_location richiesto dall'agente nel turno di conversazione precedente. Viene abbinato l'intent car_rental.return_different_location nel percorso Default Start Flow. Il percorso di completamento del modulo nella pagina Luogo di ritiro viene valutato e chiamato. Ha un completamento ("Ok, il tuo ritiro…"), che viene aggiunto alla coda di risposte con i riferimenti ai parametri risolti in valori effettivi forniti dall'utente finale. La sessione passa alla pagina Conferma posizione. La pagina Conferma posizione contiene un'opzione di completamento ("La posizione di consegna è diversa..."), che viene aggiunto alla coda delle risposte. L'agente invia la coda di risposte all'utente finale.
Utente finale:sì. Lascerò l'auto a Los Angeles. Agente: Ok, la riconsegna avverrà a Los Angeles. Agente:in quale data e ora vorresti ritirare il veicolo?	Viene abbinato l'intent car_rental.return_different_location nel percorso Default Start Flow. La sessione passa alla pagina Luogo di riconsegna. L'input dell'utente finale compila il parametro drop_off_location richiesto dall'agente nel turno di conversazione precedente. Il percorso di completamento del modulo nella pagina Luogo di consegna viene valutato e chiamato. Ha un completamento ("Ok, il tuo pacco..."), che viene aggiunto alla coda di risposte. La sessione passa alla pagina Durata del noleggio. La pagina Durata del noleggio contiene valori del modulo incompleti, quindi chiede all'utente il parametro pickup_date_time ("A che ora e in che data vuoi ritirare..."), che viene aggiunto alla coda delle risposte. L'agente invia la coda di risposte all'utente finale.
Utente finale: vorrei ritirare l'auto il 5 marzo a mezzogiorno. Agente: In quale data e ora vorresti consegnare il veicolo?	L'input dell'utente finale compila il parametro pickup_date_time richiesto dall'agente nel turno precedente della conversazione. La pagina Durata del noleggio ha un altro valore del modulo mancante, quindi chiede all'utente il parametro drop_off_date_time ("A che ora e in che data vuoi restituire..."), che viene aggiunto alla coda delle risposte. L'agente invia la coda di risposte all'utente finale.
Utente finale:15 marzo a mezzogiorno. Agente: quindi, per confermare: Ritirerai il veicolo a Las Vegas il giorno 05/03/2024 alle ore 12:00 e lo riconsegnerai a Los Angeles il giorno 15/03/2024 alle ore 12:00 Ti sembra corretto?	L'input dell'utente finale compila il parametro drop_off_date_time richiesto dall'agente nel turno di conversazione precedente. La sessione passa alla pagina Conferma durata del noleggio. La pagina Confirm Rental Duration (Conferma durata del noleggio) contiene un riepilogo dell'inserimento ("Quindi, per confermare…"), che viene aggiunto alla coda delle risposte. L'agente invia la coda di risposte all'utente finale.
Utente finale:sì, grazie. Agente: ottimo. Ora scegliamo un veicolo. Agente: vorresti un veicolo economy o di lusso?	Viene abbinato il percorso dell'intent small_talk.confirmation.yes nella pagina Conferma durata noleggio. L'agente conferma la scelta dell'utente con un messaggio ("Ottimo! Ora scegliamo…"), che viene aggiunto alla coda delle risposte. La sessione passa alla pagina Disambiguazione veicolo. Il modulo della pagina Disambiguazione veicolo non è completo, quindi l'agente utilizza il parametro vehicle_type per chiedere all'utente ("Vuoi un'auto economica o di lusso..."), che viene aggiunto alla coda delle risposte. L'agente invia la coda di risposte all'utente finale.
Utente finale: spedizione economica, per favore. Agente: vorresti la Cymbal Car o il Cymbal Truck?	Viene trovata corrispondenza con l'intent $session.params.vehicle_type="economy_vehicle". La sessione passa alla pagina Opzioni di risparmio. La pagina Opzioni economiche contiene un'opzione di completamento ("Vuoi che..."), che viene aggiunto alla coda delle risposte. L'agente invia la coda di risposte all'utente finale.
Utente finale: Cymbal Truck. Agente: Il Cymbal Truck costa 50,33 $al giorno. Può ospitare 4 persone ed è dotata di radio AM/FM. Vuoi procedere al pagamento? Utente finale: sì, grazie.	Viene trovata la route dell'intent $session.params.vehicle_type="Cymbal Truck" e viene compilato il parametro vehicle_model. La sessione passa alla pagina Conferma Cymbal Truck. La pagina Conferma Cymbal Truck contiene una voce di evasione ("Il Cymbal Truck costa 50,33 $al giorno…"), che viene aggiunto alla coda delle risposte. L'agente invia la coda di risposte 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 postale di fatturazione? Utente finale: 1800 Amphibious Blvd. Mountain View, CA Agente: qual è il codice postale di fatturazione? Utente finale: 94045 Agente: ritirerai la Cymbal Car a Las Vegas il giorno 05/03/2024 alle ore 12:00:00 e la restituirai il giorno 15/03/2024 alle ore 12:00:00. Il totale per questo viaggio sarà di 175,38 $. Agente:grazie per aver scelto il nostro servizio di noleggio e buona giornata.	La sessione passa alla pagina Pagamento. Il modulo Pagamento non è completo, quindi l'agente richiede 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 risposte e inviati man mano che l'utente risponde. Le risposte dell'utente impostano il valore di ogni parametro. La sessione passa alla pagina Conferma noleggio. La pagina Conferma noleggio contiene un'integrazione ("Ok, il ritiro è previsto per…"), che viene aggiunto alla coda delle risposte. L'agente invia la coda di risposte all'utente finale. La sessione passa alla pagina Termina sessione.

Inviare messaggi con schede da Dialogflow

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

Dialogflow può rispondere con messaggi di testo o scheda. Per rispondere con un messaggio della scheda, specificarlo come payload personalizzato in fulfillment.

Il seguente codice JSON mostra come inviare un messaggio della scheda come payload personalizzato nell'intent:

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 slash, 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 allegato all'elemento della scheda interattiva (ad esempio un pulsante).
  • Il payload JSON completo di ogni evento di interazione di chat viene inviato a Dialogflow come payload personalizzato nel parametro di query e può essere accessibile con un webhook Dialogflow interrogando il valore del campo WebhookRequest.payload.
• Considerazioni per rispondere ai comandi slash e ricevere dati da schede o finestre di dialogo:
  • Quando le app di chat Dialogflow ricevono un messaggio con un comando con 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, può farlo utilizzando un webhook Dialogflow per esaminare il payload personalizzato nel parametro di query.
  • Per visualizzare una finestra di 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 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 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 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 di 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 facilitare la connessione. Per scoprire come, consulta questo esempio di integrazione della chat per Dialogflow CX su GitHub.

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 e correggere 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 del 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, il riuso dei progetti ti aiuta a non 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 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.

Argomenti correlati

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