Fulfillment build (Dialogflow)

Il fulfillment definisce l'interfaccia di conversazione per l'Azione per ottenere l'input dell'utente e la logica per l'elaborazione dell'input e l'esecuzione dell'Azione.

Scopri di più sulla creazione delle risposte

Questa documentazione descrive come creare il fulfillment in generale. Consulta Funzionalità e Risposte per ulteriori informazioni su come gestire parti specifiche della conversazione.

Definisci la conversazione

Nota: per informazioni dettagliate su cosa puoi fare con gli intent, consulta la documentazione di Dialogflow.

Ora che hai definito le azioni, puoi creare la conversazione corrispondente. Puoi farlo creando intent Dialogflow che definiscono la grammatica o cosa devono dire gli utenti per attivare l'intent e il fulfillment corrispondente per elaborare l'intent quando viene attivato.

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

Creare intent

Fai clic sul segno + accanto alla voce di menu Intent nel riquadro 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, consulta la documentazione di Dialogflow sui contesti.
• Gli eventi attivano gli intent senza che gli utenti debbano dire nulla. Un evento di 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 ulteriori informazioni sugli intent helper integrati, consulta la nostra documentazione.
• Le frasi di addestramento definiscono ciò che gli utenti devono dire (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 fornite.

• Azione e parametri definiscono quali dati passare al fulfillment se il fulfillment è abilitato per questo intent. Sono inclusi i dati analizzati dall'input utente e il nome che puoi utilizzare nel fulfillment per rilevare l'intent attivato. Utilizzerai questo nome in seguito per mappare il tuo intent alla logica di fulfillment corrispondente. Per saperne di più sulla definizione delle azioni, consulta Azioni e parametri nella documentazione di Dialogflow.

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

• Responses è lo strumento per la creazione di risposte di 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 il completamento. Puoi utilizzarlo per fornire semplici messaggi di benvenuto o di addio. Tuttavia, è probabile che utilizzerai fulfillment per rispondere agli utenti per la maggior parte degli intent.

• Fulfillment indica se vuoi chiamare o meno il fulfillment quando viene attivato questo intent. È molto probabile che lo attiverai per la maggior parte degli intent nell'agente Dialogflow. Per visualizzare questo elemento nell'intent, devi aver attivato 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 le risposte.

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

Creare risposte di fulfillment

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

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

Ti consigliamo vivamente di utilizzare la libreria client Node.js per elaborare le richieste e restituire le risposte. Di seguito è riportata la procedura generale per l'utilizzo della libreria client:

1. Inizializza l'oggetto Dialogflow. Questo oggetto gestisce automaticamente l'ascolto delle richieste e l'analisi per elaborarle nel fulfillment.
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 seguente codice crea un'istanza di Dialogflow ed esegue alcune configurazioni standard 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 precedente utilizzando l'editor incorporato di 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, generalmente eseguirai le seguenti operazioni:

1. Esegui le logiche necessarie per elaborare l'input utente.
2. Crea le tue risposte per rispondere agli intent attivati. Prendi in considerazione la piattaforma utilizzata dagli utenti per creare le risposte appropriate. Consulta la sezione Funzionalità delle piattaforme per ulteriori informazioni su come soddisfare le risposte per piattaforme diverse.
3. Richiama la funzione ask() con la tua risposta.

Nota: quando utilizzi Cloud Functions for Firebase, le variabili globali possono essere memorizzate nella cache tra le esecuzioni delle funzioni. Per ulteriori informazioni, consulta la sezione sulla 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 della finestra di dialogo (input.number) che dà il benvenuto all'utente all'azione e fa eco un numero pronunciato da un utente per un intent di 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();
}

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

Anziché avere singoli gestori per ogni intent, puoi aggiungere una funzione di riserva. All'interno della funzione di riserva, controlla quale intent l'ha attivato e agisci di conseguenza.

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();
}

Richiesta di conferma senza corrispondenza

Quando Dialogflow non riesce a trovare una corrispondenza con alcuna grammatica di input definita nelle frasi di addestramento dei tuoi intent, attiva un intent di fallback. Gli intent di riserva in genere richiedono all'utente di fornire l'input necessario per l'Azione. Puoi fornire frasi di ripetizione specificandole nell'area Risposta di un intent di riserva oppure puoi utilizzare un webhook per fornire le 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 consente agli utenti di modificare le azioni nel corso di una conversazione. Ad esempio, un utente chiede "Che film ci sono in programmazione questa settimana?" e poi cambia contesto durante una conversazione: "Che tempo farà domani?" In questo esempio, poiché "Che tempo farà domani?" non è una risposta valida alla conversazione attivata dalla richiesta iniziale, 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 che corrisponde all'input dell'utente, l'utente viene riportato nel contesto dell'Azione.

Poiché l'assistente potrebbe interrompere l'Azione per rispondere a uno scenario senza corrispondenza valido, non utilizzare intent di riserva per soddisfare le query degli utenti. Dovresti utilizzare solo intent di riserva per riproporre all'utente 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 o eliminarlo e creare i tuoi intent di riserva per gestire correttamente i casi senza corrispondenza. Nella maggior parte dei casi, le risposte predefinite nell'intent di riserva predefinito sono troppo generiche.

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 riproporre all'utente. Definisci invece 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 sull'intent di riserva predefinito per modificarlo.

3. Specifica le frasi di richiesta per rispondere agli utenti. Queste frasi devono essere colloquiali ed essere il più utili possibile al contesto attuale dell'utente.

   Per eseguire questa operazione senza fulfillment: specifica le frasi nell'area Risposta dell'intent. Dialogflow sceglie in modo casuale le frasi da questo elenco per rispondere agli utenti finché non viene attivato un intent più specifico.

   Per eseguire questa operazione con il fulfillment:

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

   Ad esempio, la seguente funzione utilizza l'oggetto conv.data (un payload di dati arbitrario che puoi utilizzare per mantenere lo stato) della libreria client Node.js per archiviare un contatore che tiene traccia del numero di volte in cui viene attivato un intent di riserva. Se viene attivata più di una volta, l'azione si chiude. Anche se non è mostrato nel codice, devi fare in modo che altri intent reimposti questo contatore su 0 quando viene attivato un intent non di riserva. Per informazioni dettagliate su come implementare questa funzionalità, consulta l'esempio di generazione 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 intent di fallback solo in determinate situazioni. Questa operazione è utile se vuoi avere intent di riserva diversi per diversi scenari senza corrispondenza.

• Se non imposti i contesti su un intent di riserva, questo viene considerato come un intent di riserva globale che Dialogflow attiva quando non esistono altri intent. Se scegli di utilizzarne uno, devi definirne uno solo.

• Se imposti i contesti di input su un intent di riserva, Dialogflow attiva questo intent di riserva quando si verificano le seguenti condizioni:

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

  Ciò ti consente di utilizzare più intent di riserva con diversi contesti di input per personalizzare la richiesta di assenza di corrispondenza in scenari specifici.

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

Per ulteriori informazioni, consulta Contesti di Dialogflow.

Richiesta di risposta senza input

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