Fulfillment do build (Dialogflow)

O fulfillment define a interface de conversa da ação para receber a entrada do usuário e a lógica para processá-la e, por fim, cumprir a ação.

Defina sua conversa

Agora que você definiu as ações, pode criar a conversa correspondente para elas. Para fazer isso, crie intents do Dialogflow que definam a gramática ou o que os usuários precisam dizer para acionar a intent e o fulfillment correspondente para processar a intent quando ela for acionada.

É possível criar quantas intents você quiser para definir a gramática de toda a conversa.

Criar intents

Clique no sinal + ao lado do item de menu Intents na navegação à esquerda do Dialogflow. O Intent Editor aparece onde você pode inserir as seguintes informações:

  • Nome da intent é o nome exibido no ambiente de desenvolvimento integrado.
  • Os contextos permitem definir o escopo do acionamento da intent para casos específicos. Leia a documentação do Dialogflow sobre Contextos para mais informações.
  • Eventos acionam intents sem que os usuários precisem dizer nada. Um exemplo de evento é o evento GOOGLE_ASSISTANT_WELCOME, que permite que o Google Assistente invoque sua ação. Esse evento é usado para a ação padrão da ação. Consulte nossa documentação para ver mais informações sobre intents auxiliares integradas.
  • As frases de treinamento definem o que os usuários precisam dizer (gramática) para acionar a intent. Digite algumas frases (de 5 a 10) que os usuários podem dizer para acionar a intent. O Dialogflow processa automaticamente as variações naturais das frases de exemplo fornecidas.
  • Ação e parâmetros definem quais dados serão transmitidos para o fulfillment, caso ele esteja ativado para a intent. Isso inclui os dados analisados pela entrada do usuário e o nome que pode ser usado no fulfillment para detectar qual intent foi acionada. Você usará esse nome mais tarde para mapear a intent para a lógica de fulfillment correspondente. Consulte Ações e parâmetros na documentação do Dialogflow para mais informações sobre como definir ações.

  • Responses é o criador de respostas do Dialogflow, em que é possível definir a resposta a essa intent diretamente no Dialogflow, sem chamar o fulfillment. Esse recurso é útil para respostas estáticas que não exigem fulfillment. Você pode usar esse recurso para enviar mensagens simples de boas-vindas ou de despedida. No entanto, você provavelmente vai usar o fulfillment para responder aos usuários para a maioria das intents.

  • O Fulfillment especifica se você quer chamar o fulfillment quando essa intent é acionada. Você provavelmente vai ativar isso para a maioria das intents no seu agente do Dialogflow. Para ver esse item na intent, ative o fulfillment para o agente no menu Fulfillment.

Como criar respostas no Dialogflow

Para algumas intents, pode ser que o fulfillment não retorne uma resposta. Nesses casos, é possível usar o criador de respostas no Dialogflow.

Na área Respostas, forneça a resposta textual que você quer retornar aos usuários. As respostas de texto padrão são respostas de texto de TTS simples que podem funcionar em várias integrações do Dialogflow. As respostas do Google Assistente são descritas na página Respostas.

Como criar respostas de fulfillment

O código de fulfillment é hospedado na lógica de fulfillment do webhook de uma ação. Por exemplo, no exemplo do Silly Name Maker, essa lógica é encontrada em index.js para a função do Cloud para Firebase.

Quando uma intent que usa fulfillment é acionada, você recebe uma solicitação do Dialogflow contendo informações sobre a intent. Em seguida, você responde à solicitação processando a intent e retornando uma resposta. Essa solicitação e resposta são definidas pelo Webhook do Dialogflow.

É altamente recomendável usar a biblioteca de cliente do Node.js para processar solicitações e retornar respostas. Este é o processo geral para usar a biblioteca de cliente:

  1. Inicialize o objeto do Dialogflow. Esse objeto processa automaticamente a detecção e a análise de solicitações para que você possa processá-las no fulfillment.
  2. Crie funções para processar solicitações. Essas funções processam a entrada do usuário e outros componentes da intent e criam a resposta para retornar ao Dialogflow.

Inicializar o objeto Dialogflow

O código a seguir instancia o Dialogflow e faz algumas configurações padrão do Node.js para o 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
    // ...
  }

Criar funções para lidar com solicitações

Quando os usuários falam uma frase que aciona uma intent, você recebe uma solicitação do Dialogflow processada com uma função no fulfillment. Nessa função, você geralmente fará o seguinte:

  1. Realizar qualquer lógica necessária para processar a entrada do usuário.
  2. Crie respostas para responder a intents acionadas. Considere a superfície que seus usuários estão usando para construir respostas apropriadas. Consulte os recursos de superfície para mais informações sobre como disponibilizar respostas para diferentes superfícies.
  3. Chame a função ask() com sua resposta.

O código a seguir mostra como criar duas respostas de TTS que processam uma intent de invocação (input.welcome) e uma intent de caixa de diálogo (input.number) que recebe o usuário em sua ação e ecoa um número que um usuário falou para uma intent do Dialogflow com o 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();
}

O número de entrada da intent personalizada, que acompanha o código acima, usa a entidade @sys.number para extrair um número dos enunciados do usuário. Em seguida, a intent envia o parâmetro num, que contém o número do usuário, para a função no fulfillment.

Em vez de ter gerenciadores individuais para cada intent, você tem a opção de adicionar uma função substituta. Dentro da função de fallback, verifique qual intent a acionou e faça a coisa apropriada de acordo.

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

Nova solicitação sem correspondência

Quando o Dialogflow não consegue corresponder a nenhuma das gramáticas de entrada definidas nas frases de treinamento das suas intents, ele aciona uma intent substituta. As intents substitutas normalmente solicitam que o usuário forneça a entrada necessária para a ação. É possível fornecer frases de nova solicitação especificando-as na área Resposta de uma intent de fallback ou usar um webhook para fornecer respostas.

Quando a resposta de um usuário não corresponde às frases de treinamento da sua ação, o Google Assistente tenta processar a entrada. Esse comportamento facilita que os usuários mudem Ações no meio de uma conversa. Por exemplo, um usuário pergunta: "Quais filmes estão em exibição esta semana?" e, em seguida, muda o contexto no meio da conversa: "Qual é a previsão do tempo para amanhã?" Nesse exemplo, como "Qual é a previsão do tempo para amanhã?" não é uma resposta válida para a conversa acionada pela solicitação inicial, o Google Assistente tenta processar a correspondência automaticamente e mover o usuário para uma conversa adequada.

Se o Google Assistente não encontrar uma ação adequada que corresponda à entrada do usuário, o usuário retornará ao contexto da ação.

Como o Google Assistente pode interromper sua ação para responder a uma situação válida sem correspondência, não use intents substitutas como uma forma de atender às consultas do usuário. Use intents substitutas apenas para solicitar uma entrada válida ao usuário.

Para criar uma intent substituta:

  1. Clique em Intents no menu de navegação do Dialogflow.
  2. Clique em ⋮ ao lado de Criar intent e selecione Criar intent substituta. Você também pode clicar na intent de substituto padrão para editá-la.
  3. Especifique frases para responder aos usuários. Essas frases precisam ser comunicáveis e ser o mais úteis possível para o contexto atual do usuário.

    Para fazer isso sem fulfillment: especifique frases na área Resposta da intent. O Dialogflow escolhe aleatoriamente frases dessa lista para responder aos usuários até que uma intent mais específica seja acionada.

    Para fazer isso com o fulfillment:

    1. Ative a opção Ativar chamada de webhook para esta intent na seção Fulfillment dela.
    2. Na sua lógica de fulfillment, processe a intent substituta como qualquer outra, conforme descrito na seção Criar funções para processar solicitações.

    Por exemplo, a função a seguir usa o objeto conv.data (um payload de dados arbitrários que você pode usar para manter o estado) da biblioteca de cliente Node.js para armazenar um contador que rastreia quantas vezes uma intent substituta é acionada. Se for acionada mais de uma vez, a ação será encerrada. Embora isso não apareça no código, faça outras intents que redefinam esse contador como 0 quando uma intent não substituta for acionada. Consulte o exemplo Number Genie para ver detalhes de como implementar isso.

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

Como usar contextos

Use contextos se quiser que o Dialogflow acione intents de fallback apenas em determinadas situações. Isso é útil se você quer ter intents substitutas diferentes para diferentes cenários sem correspondência.

  • Se você não definir contextos em uma intent substituta, ela será considerada uma intent substituta global que o Dialogflow aciona quando nenhuma outra intent tem correspondência. Se optar por usar, defina apenas um deles.
  • Se você definir contextos de entrada em uma intent substituta, o Dialogflow acionará essa intent quando as seguintes condições forem verdadeiras:

    • Os contextos atuais do usuário são um superconjunto dos contextos definidos na intent.
    • Nenhuma outra intent corresponde.

    Isso permite usar várias intents substitutas com diferentes contextos de entrada para personalizar a nova solicitação sem correspondência para cenários específicos.

  • Se você definir um contexto de saída em uma intent substituta, manterá o usuário no mesmo contexto depois que a intent substituta for acionada e processada.

Consulte Contextos do Dialogflow (em inglês) para mais informações.

Nova solicitação sem entrada

Consulte a página Novas solicitações para ver detalhes sobre como lidar com quando o usuário não fornece mais entradas em um dispositivo de voz, como um Google Home que requer interação contínua.