Migração de fulfillment

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

Considere sua abordagem de atendimento

O código de fulfillment do projeto depende do modelo de conversação e dos recursos da plataforma de desenvolvimento. O Actions Builder introduz um novo modelo de conversação e funcionalidade que mudam a forma como você cria uma conversa e provavelmente mudará a maneira como você aborda o fulfillment do projeto. Nesta seção, descrevemos os recursos do Actions Builder que são diferentes do Dialogflow e como essas diferenças mudam a forma de implementar o código de fulfillment.

  • Mudanças na implementação de conversas

    • O Dialogflow usa um fluxo de conversação baseado em contexto e de intent para 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 turnos de conversa. Dentro de uma cena, é possível fazer a correspondência com intents específicas, assim como os contextos do Dialogflow. As transições definem para qual cena passar, com base em qual intent é correspondida.

  • Funções de webhook reutilizáveis

    • No Dialogflow, os gerenciadores de webhook estã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 oferece a capacidade de chamar uma função de várias cenas ao longo do projeto.

  • Mais maneiras de invocar webhooks

    • A abordagem de um webhook por intent no Dialogflow requer intents extras para facilitar mais lógica de conversa no fulfillment do projeto.
    • O Action Builder permite fazer chamadas de webhook de vários lugares em uma cena: ao entrar, com base em condições, no preenchimento do slot e na correspondência de intent personalizada e do sistema.

Atualizar o código de atendimento

O código de fulfillment de cada ação será diferente dependendo da complexidade e do propósito da ação. No entanto, há etapas gerais a serem seguidas ao atualizar seu 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/comandos: conv.ask → conv.add
    • Recursos da 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. Atualize o 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}))
}

Consulte o mapa de conversão de código de fulfillment abaixo para uma lista completa de métodos.

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

.

Configurar webhooks

Depois de atualizar o fulfillment, ative as chamadas do webhook em todos os cenários do projeto. Embora a ferramenta de migração migre as configurações do webhook da intent do Dialogflow, é necessário revisar essas configurações, 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 houver correspondência com a intent. No Actions Builder, é possível acionar um webhook em intents ou cenas de invocação que enviam 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 no palco
  • Depois que uma condição é avaliada como verdadeira no estágio de condição de uma cena
  • Durante a etapa de arquivamento do slot 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, é preciso considerar as mudanças no fluxo de conversas, já que isso pode mudar quando e onde você faz chamadas de webhook.

Para ativar uma chamada de webhook, siga estas etapas:

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

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

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

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

  4. Insira o gerenciador de webhooks que você definiu no código de fulfillment.

  5. Clique em Salvar.

  6. Navegue até Testar para testar a chamada de webhook e as alterações de fulfillment.

Mapa de conversão de código de fulfillment

A tabela abaixo mostra como a sintaxe do código de fulfillment do Dialogflow se transforma no código do Actions Builder. Consulte os documentos de referência do Actions Builder e do SDK para acessar 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 da intent 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 outras ferramentas abaixo:

Anterior
Migração de projetos