Evasione di build (Dialogflow)

Fulfillment definisce l'interfaccia di conversazione per la tua azione per ottenere l'input utente e la logica per elaborare l'input e, alla fine, completare l'azione.

Scopri di più sulla creazione delle risposte

In questa documentazione viene descritto come creare il fulfillment in generale. Per saperne di più su come gestire parti specifiche della conversazione, consulta Funzionalità di Surface e Risposte.

Definisci la conversazione

Nota: consulta la documentazione di Dialogflow per i dettagli completi su ciò che puoi fare con gli intent.

Dopo aver definito le azioni, puoi creare la conversazione corrispondente per tali azioni. A questo scopo, crea gli intent Dialogflow che definiscono la grammatica o ciò che gli utenti hanno da dire per attivare l'intent e il relativo fulfillment per elaborare l'intent quando viene attivato.

Puoi creare tutti gli intent che vuoi definire la grammatica dell'intera conversazione.

Crea intent

Fai clic sul segno + accanto alla voce di menu Intent nella barra di navigazione a sinistra di Dialogflow. Viene visualizzato l'editor di intent in cui puoi inserire le seguenti informazioni:

• Nome intent è il nome dell'intent visualizzato nell'IDE.
• I contesti ti consentono di limitare l'attivazione dell'intent a casi specifici. Per ulteriori informazioni, leggi la documentazione di Dialogflow su Contesto.
• Gli eventi attivano intent senza che gli utenti debbano fare nulla. Un esempio è l'evento GOOGLE_ASSISTANT_WELCOME, che consente all'Assistente Google di richiamare l'azione. Questo evento viene utilizzato per l'azione predefinita dell'azione. Per saperne di più sugli intent predefiniti di supporto, consulta la documentazione.
• Le frasi di addestramento definiscono ciò che gli utenti devono dire (la grammatica) per attivare l'intent. Digita alcune frasi qui (5-10) di ciò che gli utenti possono dire per attivare l'intent. Dialogflow gestisce automaticamente le varianti naturali delle frasi di esempio che fornisci.

• Azione e parametri definiscono quali dati passare al fulfillment, se abilitati per questo intent. Sono inclusi i dati analizzati dall'input dell'utente e il nome che puoi utilizzare nel fulfillment per rilevare quale intento è stato attivato. Utilizzerai questo nome in seguito per mappare il tuo intento alla logica di evasione corrispondente. Per ulteriori informazioni sulla definizione delle azioni, consulta la sezione Azioni e parametri nella documentazione di Dialogflow.

  Nota: il termine "Azione" si riferisce al componente specifico di un intent di Dialogflow e non al concetto più ampio di un'Azione nella piattaforma Actions on Google.

• Risposte è il builder di risposte Dialogflow, in cui puoi definire la risposta a questo intent direttamente all'interno di Dialogflow, senza chiamare il fulfillment. Questa funzionalità è utile per le risposte statiche che non richiedono l'evasione. Può essere utile per fornire messaggi di benvenuto o di saluto. Tuttavia, è probabile che utilizzerai la distribuzione per rispondere ai tuoi utenti per la maggior parte degli intent.

• Fulfillment specifica se vuoi o meno chiamare il tuo fulfillment quando questo intento è attivato. Molto probabilmente attiverai questa opzione per la maggior parte degli intent nel tuo agente Dialogflow. Per vedere questo elemento nell'intent, devi aver abilitato il fulfillment per l'agente nel menu Fulfillment.

Creazione di risposte in Dialogflow

Per alcuni intent, potrebbe non essere necessario che il fulfillment restituisca una risposta. In questi casi, puoi utilizzare il generatore di risposte in Dialogflow per creare risposte.

Nell'area Risposte, indica la risposta testuale che vuoi restituire agli utenti. Le risposte di testo predefinite sono semplici risposte di testo TTS che possono funzionare su più integrazioni Dialogflow. Le risposte per l'Assistente Google sono descritte nella pagina Risposte.

Creazione di risposte di evasione degli ordini

Il codice di evasione è ospitato nella logica di evasione dei webhook per un'azione. Ad esempio, nell'esempio di Silly Name Maker, questa logica si trova in index.js per la funzione Cloud Functions for Firebase.

Quando viene attivato un intent che utilizza il fulfillment, ricevi una richiesta da Dialogflow che contiene informazioni sull'intent. Quindi, rispondi alla richiesta elaborando l'intent e restituendo una risposta. Questa richiesta e risposta è definita dal webhook di Dialogflow.

Ti consigliamo vivamente di utilizzare la libreria client Node.js per elaborare le richieste e restituire le risposte. Ecco la procedura generale per utilizzare la libreria client:

1. Inizializza l'oggetto Dialogflow. Questo oggetto gestisce automaticamente l'ascolto delle richieste e l'analisi, in modo da poterle elaborare nell'evasione ordini.
2. Creare funzioni per gestire le richieste. Queste funzioni elaborano l'input utente e altri componenti dell'intent e creano la risposta per tornare a Dialogflow.

Inizializza l'oggetto Dialogflow

Il codice seguente crea l'istanza di Dialogflow ed esegue alcune configurazioni boilerplate di Node.js per Google Cloud Functions:

Node.js

'use strict';

const {dialogflow} = require('actions-on-google');
const functions = require('firebase-functions');

const app = dialogflow({debug: true});

app.intent('Default Welcome Intent', (conv) => {
  // Do things
});
exports.yourAction = functions.https.onRequest(app);

Java

public class DfFulfillment extends DialogflowApp {
  private static final Logger LOGGER = LoggerFactory.getLogger(DfFulfillment.class);

  @ForIntent("Default Welcome Intent")
  public ActionResponse welcome(ActionRequest request) {
    // Do things
    // ...
  }

Nota: se esegui il deployment del codice sopra riportato utilizzando l'editor in linea di fulfillment Dialogflow, cambia exports.yourAction in exports.dialogflowFirebaseFulfillment.

Creare funzioni per gestire le richieste

Quando gli utenti pronunciano una frase che attiva un intent, ricevi una richiesta da Dialogflow che gestisci con una funzione nel tuo fulfillment. In questa funzione, solitamente devi eseguire le seguenti operazioni:

1. Eseguire qualsiasi logica necessaria per elaborare l'input utente.
2. Crea le tue risposte in modo che rispondano agli intent attivati. Tieni conto della superficie utilizzata dagli utenti per creare risposte appropriate. Per ulteriori informazioni su come soddisfare le risposte relative a piattaforme diverse, consulta le funzionalità della superficie.
3. Richiama la funzione ask() con la risposta.

Nota: quando utilizzi Cloud Functions for Firebase, le variabili globali possono essere memorizzate nella cache nelle esecuzioni di funzioni. Per ulteriori informazioni, leggi la durata delle istanze di funzione nella documentazione di Google Cloud.

Il codice seguente mostra come creare due risposte TTS che gestiscono un intent di chiamata (input.welcome) e un intent di finestra di dialogo (input.number) che accogli l'utente sulla tua azione e riconosca un numero che un utente ha letto per un intent Dialogflow con il nome:

Node.js

const app = dialogflow();
app.intent('Default Welcome Intent', (conv) => {
conv.ask('Welcome to number echo! Say a number.');
});
app.intent('Input Number', (conv, {num}) => {
// extract the num parameter as a local string variable
conv.close(`You said ${num}`);
});

Java

@ForIntent("Default Welcome Intent")
public ActionResponse defaultWelcome(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  rb.add("Welcome to number echo! Say a number.");
  return rb.build();
}

@ForIntent("Input Number")
public ActionResponse inputNumber(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  Integer number = (Integer) request.getParameter("num");
  rb.add("You said " + number.toString());
  return rb.endConversation().build();
}

L'intent di input personalizzato che accompagna il codice sopra riportato utilizza l'entità @sys.number per estrarre un numero dalle frasi degli utenti. L'intent invia il parametro num, che contiene il numero dell'utente, alla funzione nel fulfillment.

Invece di avere singoli gestori per ogni intent, puoi aggiungere una funzione di riserva in alternativa. All'interno della funzione di fallback, controlla quale intento lo ha attivato e agisci nel modo appropriato.

Node.js

const WELCOME_INTENT = 'Default Welcome Intent';
const NUMBER_INTENT = 'Input Number';
const NUMBER_PARAMETER = 'num';
// you can add a fallback function instead of a function for individual intents
app.fallback((conv) => {
 // intent contains the name of the intent
 // you defined in the Intents area of Dialogflow
 const intent = conv.intent;
 switch (intent) {
   case WELCOME_INTENT:
     conv.ask('Welcome! Say a number.');
     break;
   case NUMBER_INTENT:
     const num = conv.parameters[NUMBER_PARAMETER];
     conv.close(`You said ${num}`);
     break;
 }
});

Java

// you can add a fallback function instead of a function for individual intents
@ForIntent("Default Fallback Intent")
public ActionResponse fallback(ActionRequest request) {
  final String WELCOME_INTENT = "Default Welcome Intent";
  final String NUMBER_INTENT = "Input Number";
  final String NUMBER_ARGUMENT = "num";
  // intent contains the name of the intent
  // you defined in the Intents area of Dialogflow
  ResponseBuilder rb = getResponseBuilder(request);
  String intent = request.getIntent();
  switch (intent) {
    case WELCOME_INTENT:
      rb.add("Welcome! Say a number.");
      break;
    case NUMBER_INTENT:
      Integer num = (Integer) request.getParameter(NUMBER_ARGUMENT);
      rb.add("You said " + num).endConversation();
      break;
  }
  return rb.build();
}

Nessuna richiesta di corrispondenza

Quando Dialogflow non corrisponde a nessuna delle grammatica di input definite nelle frasi di addestramento degli intent, attiva un intent di riserva. In genere, gli intent di fallback invitano l'utente a fornire l'input necessario per la tua azione. Puoi fornire frasi di richiesta specificandole nell'area Risposta di un intent di riserva oppure puoi utilizzare un webhook per fornire risposte.

Quando la risposta di un utente non corrisponde alle frasi di addestramento dell'azione, l'Assistente Google tenta di gestire l'input. Questo comportamento facilita la modifica delle azioni durante una conversazione. Ad esempio, un utente chiede: "Che film ci sono questa settimana?" e poi cambia il contesto a metà della conversazione: "Che tempo farà domani?". In questo esempio, perché "Che tempo fa domani?" non è una risposta valida alla conversazione attivata dalla richiesta iniziale, quindi l'assistente tenta automaticamente di gestire la corrispondenza e di spostare l'utente in una conversazione appropriata.

Se l'assistente non riesce a trovare un'azione appropriata corrispondente all'input dell'utente, l'utente viene riportato nel contesto della tua azione.

Poiché l'assistente potrebbe interrompere l'azione per rispondere a uno scenario valido senza corrispondenza, non utilizzare gli intent di riserva per soddisfare le query degli utenti. Dovresti utilizzare gli intent di fallback solo per chiedere nuovamente agli utenti un input valido.

Nota: per impostazione predefinita, Dialogflow crea automaticamente un Intent di riserva predefinito per ogni agente. Devi modificare le risposte fornite da questo intent oppure eliminarle e creare i tuoi intent di riserva per gestire correttamente i casi che non corrispondono. Nella maggior parte dei casi, le risposte predefinite in Intent di riserva predefinito sono troppo generali.

Avviso: non utilizzare intent di riserva per tentare di soddisfare le query degli utenti. Gli intent di riserva e la gestione senza corrispondenza devono essere utilizzati solo per chiedere nuovamente all'utente. Definisci un'azione che utilizzi l'entità @sys.any.

Per creare un intent di riserva:

1. Fai clic su Intent nel menu di navigazione di Dialogflow.
2. Fai clic su ⋮ accanto a Crea intent e seleziona Crea intent di riserva. In alternativa, fai clic su Intent di riserva predefinito per modificarlo.

3. Specifica le frasi di ripetizione da mostrare agli utenti. Queste frasi devono essere colloquiali ed essere il più utili possibile nel contesto attuale dell'utente.

   Per farlo senza completamento: specifica le frasi nell'area Risposta dell'intent. Dialogflow sceglie in modo casuale le frasi di questo elenco per parlare con gli utenti finché non viene attivato un intent più specifico.

   Per farlo con l'evasione dell'ordine:

   1. Attiva/disattiva Attiva chiamata webhook per questo intent nella sezione Fulfillment dell'intent.
   2. Nella logica di fulfillment, gestisci l'intent di riserva come tutti gli altri intent, come descritto nella sezione Creare funzioni per gestire le richieste.

   Ad esempio, la funzione riportata di seguito utilizza l'oggetto conv.data (un payload di dati arbitrari che puoi utilizzare per mantenere lo stato) dalla libreria client Node.js per archiviare un contatore che tracce quante volte viene attivato un intent di riserva. Se viene attivato più di una volta, l'azione si chiude. Sebbene non sia visualizzato nel codice, devi fare in modo che altri intent reimpostano questo contatore su 0 quando viene attivato un intent non di riserva. Per maggiori dettagli su come implementare questa funzionalità, consulta l'esempio di numie di numeri.

   Node.js

   app.intent('Default Fallback Intent', (conv) => {
    conv.data.fallbackCount++;
    // Provide two prompts before ending game
    if (conv.data.fallbackCount === 1) {
      conv.contexts.set(DONE_YES_NO_CONTEXT, 5);
      conv.ask('Are you done playing Number Genie?');
    } else {
      conv.close(`Since I'm still having trouble, so I'll stop here. ` +
        `Let's play again soon.`);
    }
   });

   Java

   @ForIntent("Default Fallback Intent")
   public ActionResponse defaultFallback(ActionRequest request) {
     final String DONE_YES_NO_CONTEXT = "done_yes_no_context";
     ResponseBuilder rb = getResponseBuilder(request);
   
     int fallbackCount =
         request.getConversationData().get("fallbackCount") == null
             ? 0
             : (Integer) request.getConversationData().get("fallbackCount");
     fallbackCount++;
     request.getConversationData().put("fallbackCount", fallbackCount);
   
     if (fallbackCount == 1) {
       rb.add(new ActionContext(DONE_YES_NO_CONTEXT, 5));
       rb.add("Are you done playing Number Genie?");
     } else {
       rb.add("Since I'm still having trouble, so I'll stop here. Let's play again soon")
           .endConversation();
     }
     return rb.build();
   }

Utilizzo dei contesti

Utilizza i contesti se vuoi che Dialogflow attivi gli intent di riserva solo in determinate situazioni. Questo è utile se vuoi avere intent di riserva diversi per scenari di mancata corrispondenza diversi.

• Se non imposti contesti su un intent di riserva, questo viene considerato un intent di riserva globale che Dialogflow attiva quando non è presente alcuna corrispondenza con un altro intent. Devi averne definito uno solo se scegli di utilizzarne uno.

• Se imposti i contesti di input per un intent di riserva, Dialogflow attiva questo intent di riserva quando le seguenti condizioni sono vere:

  • I contesti attuali dell'utente sono un soprainsieme dei contesti definiti nell'intent.
  • Nessun altro intent corrisponde.

  In questo modo puoi utilizzare più intent di riserva con contesti di input diversi per personalizzare la mancata corrispondenza in base a scenari specifici.

• Se imposti un contesto di output su un intent di riserva, mantieni l'utente nello stesso contesto dopo che questo è stato attivato ed elaborato.

Per ulteriori informazioni, vedi Contesto di Dialogflow.

Nessuna richiesta di input

Consulta la pagina Suggerimenti per informazioni dettagliate su come gestire i casi in cui l'utente non fornisce ulteriori informazioni su un dispositivo vocale, ad esempio Google Home, che richiede un'interazione continua.