Migração de fulfillment

Depois de configurar as intents e cenas, atualize o código de fulfillment para considerar as mudanças nos formatos de solicitação e resposta do Action Builder. Esta também é uma oportunidade de considerar o uso de outros recursos do Actions Builder. Esta página aborda etapas e considerações gerais para atualizar seu código de fulfillment.

Considere sua abordagem de atendimento

O código de fulfillment do projeto depende do modelo conversacional e dos recursos da plataforma de desenvolvimento. O Actions Builder apresenta um novo modelo conversacional e uma nova funcionalidade que mudam a forma como você cria uma conversa e provavelmente a como você aborda o cumprimento do projeto. Nesta seção, descrevemos os recursos do Actions Builder que diferem do Dialogflow e como essas diferenças alteram a maneira como você implementa seu código de fulfillment.

  • Mudanças na implementação de conversas

    • O Dialogflow usa um fluxo de conversação baseado em contexto na intent para a intent, em que as intents individuais são correspondidas com base nas frases de treinamento e nos contextos de entrada/saída da intent anterior.
    • O fluxo de conversa do Actions Builder usa cenas como um contêiner para rodadas de conversa. Dentro de um cenário, é possível associar intents específicas, assim como os contextos do Dialogflow. As transições definem para qual cena fazer a transição, com base em qual intent é correspondida.

  • Funções de webhook reutilizáveis

    • No Dialogflow, os gerenciadores de webhook são vinculados a intents individuais. Se for necessária uma lógica adicional, crie uma intent separada para processar a nova função.
    • Os gerenciadores de webhook têm nomes de gerenciador personalizados no Actions Builder. Esse recurso permite chamar uma função a partir de várias cenas do projeto.

  • Outras maneiras de invocar webhooks

    • A abordagem de um webhook por intent no Dialogflow exige mais intents para facilitar a lógica de conversação no fulfillment do projeto.
    • O Action Builder permite que você faça chamadas de webhook de vários lugares em uma cena: na entrada, com base nas condições, no preenchimento de slot e usando a correspondência personalizada e de intents do sistema.

Atualizar seu código de atendimento

O código de fulfillment de cada ação varia de acordo com a complexidade e o propósito dela. No entanto, há etapas gerais a serem seguidas ao atualizar o código:

  1. Faça o download e instale a versão mais recente da biblioteca de cliente.

    npm install @assistant/conversation

  2. Atualize as instruções require no código. Exemplo:

    const {
  SimpleResponse,
  BasicCard,
  Image,
} = require('actions-on-google');

    O código acima foi atualizado para o seguinte:

    const {
  conversation,
  Simple,
  Card,
  Image,
} = require('@assistant/conversation');

  3. Refatore o código para usar os novos métodos.

    • Gerenciadores de intent: app.intent → app.handle
    • Resposta/solicitações: conv.ask → conv.add
    • Recursos de superfície/dispositivo: conv.surface.capabilities.has('actions.capability.SCREEN_OUTPUT') → conv.device.capabilities.includes('RICH_RESPONSE')
    • Armazenamento de dados: conv.data → conv.session.params

    • Tipos de resposta:

      • SimpleResponse → Simple
      • BasicCard → Card
      • Suggestions → Suggestion

    • Parâmetros de intent: conv.parameters[KEY] → conv.intent.parameters[KEY].resolved

    • Contextos/transições de cena: conv.contexts.set(content_name, 5); → conv.scene.next.name = 'context_name'

    • Encerrar conversa: conv.close(response) → conv.add.response; conv.scene.next.name = 'actions.page.END_CONVERSATION'

  4. Atualização do código de resposta para utilizar os novos primitivos de resposta do Builder. Exemplo:

    conv.ask(new Suggestions (['a', 'b']));

    O código acima foi atualizado para o seguinte:

    for (suggestion of ['a', 'b']) {
  conv.add.(new Suggestion({title: suggestion}))
}

Veja o mapa de tradução do código de atendimento abaixo para uma lista completa dos métodos.

Use as páginas a seguir para comparar payloads de solicitação e resposta:

Configurar webhooks

Depois de atualizar o fulfillment, ative chamadas de webhook em todas as cenas do projeto. A ferramenta de migração pode migrar as configurações de webhook da intent do Dialogflow, mas é necessário revisá-las, porque o código de fulfillment refatorado e as funções do webhook podem mudar.

No Dialogflow, os webhooks são ativados nas intents, e o código de fulfillment inclui gerenciadores e funções a serem executados quando a intent é correspondida. No Actions Builder, um webhook pode ser acionado em intents ou cenas de invocação, que envia uma solicitação ao endpoint de fulfillment. O fulfillment contém gerenciadores de webhook que processam o payload JSON na solicitação. É possível acionar webhooks nas seguintes situações:

  • Após uma correspondência de intent de invocação
  • Durante a entrada de uma cena
  • Depois que uma condição for avaliada como verdadeira no estágio de condição de um cenário
  • Durante o estágio de arquivamento de slots de uma cena
  • Depois que uma correspondência de intent ocorre no estágio de entrada de uma cena

Ao migrar do Dialogflow para o Actions Builder, você precisa considerar as mudanças no fluxo de conversa, já que elas podem mudar quando e onde você faz chamadas de webhook.

Para ativar uma chamada de webhook, siga estas etapas:

  1. Selecione o cenário do qual você quer chamar o webhook.

  2. Escolha o estado em que você quer ativar o webhook. É possível ativar um webhook para um ou mais dos seguintes estados:

    • Ao inserir
    • Condição
    • Preenchimento de slots
    • Processamento da intent do usuário
    • Processamento de intents do sistema

  3. Marque a opção Call your webhook.

  4. Insira o gerenciador de webhook definido no código de fulfillment.

  5. Clique em Salvar.

  6. Navegue até Testar para testar as mudanças de chamada e fulfillment do webhook.

Mapa de conversão de código de atendimento

A tabela abaixo mostra como a sintaxe do código de fulfillment do Dialogflow se traduz no código do Actions Builder. Consulte a documentação de referências do SDK e do Actions Builder para ver uma lista completa de métodos.

Dialogflow Criador de ações
conv.data conv.session.params
conv.ask conv.add
conv.close conv.scene.next.name = 'actions.scene.END_CONVERSATION'
conv.user.storage conv.user.params
conv.input.raw conv.intent.query
conv.parameters conv.intent.params[key].resolved
conv.arguments.get('MEDIA_STATUS')
mediaStatus.status==='FINISHED'		 conv.intent.params['MEDIA_STATUS']
mediaStatus.resolved==='FINISHED'
Eventos Processamento de intents do sistema:
MEDIA_STATUS_FINISHED
MEDIA_STATUS_FAILED
conv.device.capabilities.has("actions.capability.SCREEN_OUTPUT") conv.device.capabilities.includes("RICH_RESPONSE")
app.intent app.handler
app.middleware app.middleware
Resposta simples prompt -firstSimple
Resposta avançada prompt -content -card: object -image: object -table: object -media: object -suggestions -link

Você pode encontrar informações sobre ferramentas adicionais abaixo:

Anterior
Migração de projetos