Manipuladores de estado

Manipuladores de estado, também chamados simplesmente de manipuladores, são usados para controlar a conversa criando respostas para usuários finais e/ou fazendo a transição da página atual. Para cada fala na conversa, os manipuladores são avaliados e podem afetar a sessão. Os manipuladores têm três tipos gerais de dados:

Termo Definição
Requisitos do manipulador Estes são os requisitos que precisam ser atendidos para que o manipulador tenha efeito na sessão. Um manipulador é chamado de chamado quando atende aos requisitos e afeta a sessão de alguma forma.
Fulfillment do manipulador Se um manipulador for chamado, um fulfillment opcional será usado para criar respostas para os usuários finais. Essas respostas são definidas nos dados do agente estático ou recuperadas dinamicamente do serviço de webhook.
Meta de transição do manipulador Se um manipulador for chamado, um destino de transição opcional será usado para alterar a página atual. A próxima página só pode ser uma página inicial de fluxo ou uma página dentro do fluxo ativo no momento.

Há dois tipos de manipuladores de estado com requisitos de gerenciador diferentes:

Termo Definição
Rotas Rotas são chamadas quando uma entrada de usuário final corresponde a uma intent e/ou quando alguma condição no status da sessão é atendida. Uma rota com um requisito de intent também é chamada de rota de intent. Uma rota com apenas um requisito de condição também é chamada de rota de condição.
Manipuladores de eventos Os manipuladores de eventos são chamados quando um evento é invocado. Alguns eventos integrados são acionados quando a entrada inesperada do usuário final é recebida ou quando ocorre um erro do webhook. Também é possível definir eventos personalizados que são invocados quando algo acontece fora da conversa.

Há três etapas para processar um manipulador de estado:

Termo Definição
1. escopo O manipulador precisa estar no escopo para ter efeito na sessão. O escopo é determinado pela aplicação de um gerenciador a um fluxo, a uma página ou a um parâmetro de formulário, e se o fluxo associado estiver ativo, a página associada estiver ativa ou se o agente estiver tentando preencher o parâmetro do formulário associado.
2. Avaliação Cada manipulador no escopo é avaliado em ordem. Se os requisitos de um manipulador forem atendidos, ele será aprovado na avaliação.
3. Chamada Se um manipulador estiver no escopo e passar na avaliação, ele será chamado. Qualquer fulfillment associado será chamado, e qualquer meta de transição associada será aplicada à sessão.

escopo

Para que um manipulador seja avaliado, ele precisa estar no escopo. O escopo do manipulador é uma ferramenta importante e eficiente que ajuda você a controlar a conversa. Ao controlar o escopo de um manipulador, você pode controlar:

X Item
Quando uma intent pode ser correspondida
Quando uma condição precisa ser verificada
Quando um determinado evento pode ser manipulado
Quando uma transição de página pode ocorrer
Quando uma resposta de conclusão estática é fornecida
Quando um fulfillment ativado para webhook é chamado para respostas dinâmicas

O escopo é determinado se um manipulador for aplicado a um fluxo, a uma página ou a um parâmetro de formulário, e se o fluxo associado estiver ativo, a página associada estiver ativa ou se o agente estiver tentando preencher o parâmetro de formulário associado.

As regras de escopo detalhadas são as seguintes:

  • Rotas de transição aplicadas ao fluxo ativo:
    • Se a página atual for a página inicial do fluxo, ela estará no escopo.
    • Se a página atual não for a página inicial do fluxo, ela estará no escopo somente se tiver um requisito de intent.
  • As rotas aplicadas à página atual estão no escopo.
  • Os manipuladores de eventos aplicados ao fluxo ativo estão no escopo.
  • Os manipuladores de evento aplicados à página atual estão no escopo.
  • Os manipuladores de evento aplicados a um parâmetro de formulário que o agente está tentando preencher no escopo.

Rotas

As rotas têm dois requisitos, e um ou ambos precisam ser fornecidos. Se os dois requisitos forem fornecidos, ambos precisarão ser atendidos para chamar o trajeto:

Termo Definição
Requisito de intent Uma intent que precisa corresponder à entrada do usuário final para a rodada de conversa atual. Quando uma rota tem um requisito de intent, ela é chamada de rota de intent.
Requisito de condição Uma condição que precisa ser atendida. Quando uma rota tem um requisito de condição, ela é chamada de rota de condição.

Você pode aplicar rotas a fluxos (rotas no nível de fluxo) e a páginas (rotas no nível da página). Por exemplo, é possível usar rotas nas seguintes situações:

X Item
Quando a entrada do usuário final corresponde a uma intent, a correspondência precisa acionar uma resposta de fulfillment estático.
Quando a entrada do usuário final corresponde a uma intent, a correspondência precisa acionar um fulfillment ativado para webhook para uma resposta dinâmica.
Quando a entrada do usuário final fornece o parâmetro de formulário final exigido, uma verificação de condição aciona uma transição de sessão para outra página.
Quando a entrada do usuário final tiver fornecido um parâmetro de formulário específico, uma verificação de condição acionará uma resposta de fulfillment estático.
Uma verificação de condição definida como true que força uma transição de página.

Propagação de intents

Normalmente, quando uma rota é chamada devido a uma intent correspondente, ela é consumida. Uma intent consumida não pode ser correspondida novamente, a menos que uma nova entrada de usuário final acione uma nova correspondência de intent. No entanto, é possível propagar uma correspondência de intent de um fluxo para outro no seguinte cenário:

  • Uma rota em flow F1 tem intent I1 como um requisito e flow F2 como um destino de transição.
  • Flow F2 tem uma rota que também tem intent I1 como um requisito.

Nesse caso, quando a rota em flow F1 é chamada, intent I1 é correspondido duas vezes para uma única entrada de usuário final, e ambas as rotas são chamadas.

Propagar intents é útil para:

X Item
Altere a página atual para uma página específica em outro fluxo (a rota do fluxo de destino de transição tem uma página de destino de transição específica).
Crie uma mensagem de entrada para a página inicial de um fluxo (a rota do fluxo de conversão de transição tem um fulfillment).

Grupos de rotas

Ao criar um agente, é possível descobrir que muitas páginas têm um conjunto comum de rotas. Para tornar os trajetos reutilizáveis, você pode definir grupos de trajetos. Esses grupos são um recurso para todo o fluxo.

Por exemplo, você pode querer que seu fluxo lide com a entrada do usuário final, como "Quero adicionar uma cobertura à minha pizza" e "Quero alterar o tamanho da minha bebida". Essas entradas devem ser tratadas quando qualquer uma das várias páginas do fluxo estiver ativa. É possível definir duas rotas com intents para processar essas entradas em todas as páginas relevantes, mas isso é muito trabalho duplicado. Em vez disso, é possível definir o grupo de rotas uma vez e adicionar uma referência ao grupo em todas as páginas relevantes.

Rotas de nível de fluxo

Rotas de nível do fluxo são rotas aplicadas a um fluxo. Esses tipos de manipuladores têm os seguintes casos de uso:

X Item
Manipuladores com um requisito de intent ou condição no escopo da página inicial do fluxo.
Os manipuladores com um requisito de intent no escopo de todas as páginas dentro do fluxo.

Rotas no nível da página

Rotas no nível da página são rotas aplicadas a uma página. Esses tipos de manipuladores têm os seguintes casos de uso:

X Item
Manipuladores com uma exigência de intent ou condição no escopo quando páginas específicas estão ativas.

Manipuladores de eventos

Os manipuladores de eventos têm um requisito para serem chamados:

Termo Definição
Requisito do evento Um evento que precisa ser invocado. Os eventos são identificados pelo nome. Alguns eventos integrados são invocados quando a entrada inesperada do usuário final é recebida ou quando ocorre um erro do webhook. Também é possível definir eventos personalizados que são invocados quando algo acontece fora da conversa.

Você pode aplicar manipuladores de eventos a fluxos (manipuladores de eventos no nível do fluxo), páginas (manipuladores de eventos no nível da página) e parâmetros (manipuladores de eventos no nível do parâmetro). Por exemplo, você pode usar manipuladores de eventos nas seguintes situações:

X Item
Quando a entrada do usuário final não corresponde a nenhuma intent, um manipulador de eventos no-match fornece uma resposta fulfillment estática específica.
Um timer expira no sistema, e você quer fornecer informações de lembrete ao usuário final com uma resposta de fulfillment estático específica.

Manipuladores de eventos no nível do fluxo

Os manipuladores de eventos no nível do fluxo são manipuladores de eventos aplicados a um fluxo. Esses tipos de manipuladores têm os seguintes casos de uso:

X Item
Manipuladores com um requisito de evento no escopo da página inicial do fluxo.
Os manipuladores com um requisito de evento no escopo de todas as páginas dentro do fluxo.
Lidar com entradas inesperadas do usuário final, compartilhadas por todas as páginas em um fluxo.
Lidar com erros de webhook, compartilhados por todas as páginas em um fluxo.
Lidar com eventos personalizados invocados pelo sistema, compartilhados por todas as páginas em um fluxo.

Cada fluxo tem manipuladores de eventos para o no-match e no-input eventos integrados. Esses manipuladores de eventos são criados automaticamente quando você cria um fluxo e não podem ser excluídos.

Manipuladores de eventos no nível da página

Os manipuladores de eventos no nível da página são manipuladores de eventos aplicados a uma página. Esses tipos de manipuladores têm os seguintes casos de uso:

X Item
Manipualdres com um requisito de evento no escopo quando páginas específicas estão ativas.
Lidar com entradas inesperadas do usuário final específicas de uma página.
Como lidar com erros de webhook, específicos de uma página.
Lidar com eventos personalizados invocados pelo sistema, específicos de uma página.

Manipuladores de eventos no nível do parâmetro

Os manipuladores de eventos no nível do parâmetro são manipuladores de eventos aplicados a um parâmetro de formulário. Eles também são conhecidos como gerenciadores de solicitações novas (reprompt). Esses manipuladores de eventos não permitem eventos personalizados, pois se destinam especificamente a processar entradas de usuário final inválidas durante o preenchimento do formulário.

Esses tipos de manipuladores têm os seguintes casos de uso:

X Item
O usuário final não forneceu uma entrada válida quando solicitado a preencher um parâmetro de formulário.

Eventos integrados

Os eventos a seguir estão integrados. Alguns eventos são restritos a determinados níveis.

Nome do evento
Nível do fluxo Nível da página Nível do parâmetro Quando foi invocado
sys.no-match-default A entrada do usuário final não corresponde a nenhuma intent de gerenciadores que estão no escopo nem satisfazem parâmetros de formulário.
sys.no-match-[1-6] Se você fornecer gerenciadores para qualquer um desses eventos numerados, eles serão invocados em vez de sys.no-match-default e na ordem: sys.no-match-1, sys.no-match-2, ...
sys.no-input-default A entrada do usuário final não foi recebida.
sys.no-input-[1-6] Se você fornecer gerenciadores para qualquer um desses eventos numerados, eles serão invocados em vez de sys.no-input-default e na ordem: sys.no-input-1, sys.no-input-2, ...
sys.invalid-parameter Invocado quando um webhook invalida o parâmetro.
webhook.error A chamada do webhook retornou um erro.
webhook.error.timeout A chamada do webhook expirou.

Eventos personalizados

É possível criar eventos personalizados e manipuladores de eventos. Os eventos são simplesmente identificados pelo nome, mas é preciso evitar o uso de nomes de eventos integrados para evitar conflitos.

Para invocar um evento com a API, consulte o campo queryParams.event do método detectIntent na

Selecione um protocolo e uma versão para a referência de sessão:

Protocolo V3beta1
REST Recurso da sessão
RPC Interface da sessão

Ordem de avaliação

Os manipuladores são avaliados em uma ordem específica. Aplicam-se as seguintes regras gerais:

  1. Somente manipuladores no escopo são avaliados.
  2. Somente os manipuladores com requisitos que podem ser atendidos podem ser chamados.
  3. Se um manipulador sem um destino de transição for chamado, a avaliação da lista de gerenciadores continuará. Devido a essa regra, vários fulfillments podem adicionar mensagens à fila de resposta.
  4. Se um manipulador com um destino de transição for chamado, a avaliação da lista de manipuladores será concluída.
  5. Se um manipulador com fulfillment for chamado e o fulfillment resultar em um erro de webhook:
    • Quando um manipulador de eventos está no escopo do evento, ele manipula o evento e a avaliação da lista de manipuladores termina.
    • Se nenhum manipulador de eventos estiver no escopo do evento, o webhook falhará silenciosamente.
  6. Quando um requisito de intent ou de condição é atendido, a intent ou a condição não é consumida. Portanto, várias rotas com a mesma intent ou condição podem ser chamadas.
  7. Quando um requisito de evento é atendido, o evento é consumido. Portanto, somente o primeiro manipulador de eventos encontrado para o evento pode ser chamado.

Há três fases na avaliação:

  1. As rotas que têm um requisito de intent são avaliadas nesta ordem:
    1. Nível da página: rotas individuais aplicadas à página atual, na ordem fornecida.
    2. Grupos no nível da página: grupos de rota aplicados à página atual, na ordem fornecida.
    3. Nível do fluxo: rotas aplicadas ao fluxo ativo, na ordem fornecida.
  2. As rotas de transição com apenas um requisito de condição são avaliadas nesta ordem:
    1. Nível da página: rotas individuais aplicadas à página atual, na ordem fornecida.
  3. Os manipuladores de eventos são avaliados nesta ordem:
    1. Nível do parâmetro: os manipuladores de eventos aplicados ao parâmetro do formulário da página que o agente está tentando preencher (gerenciadores de reprompts) na ordem fornecida.
    2. Nível da página: manipuladores de eventos aplicados à página atual, na ordem fornecida.
    3. Nível de fluxo: manipuladores de eventos aplicados ao fluxo ativo, na ordem fornecida.

Alvos de transição simbólica

Ao inserir uma meta de transição para um manipulador, é possível inserir fluxos ou páginas específicos, assim como inserir metas de transição simbólica:

Alvo de transição simbólica
Descrição
START_PAGE Transição para a página inicial do fluxo ativo com nome semelhante.
END_FLOW Encerre o fluxo ativo e volte para a página que causou uma transição para o fluxo atual.
END_SESSION Limpe a sessão atual e faça a transição para a página especial chamada END_SESSION. A próxima entrada do usuário reiniciará a sessão na página inicial do Fluxo de início padrão.
PREVIOUS_PAGE Transição para a página anterior.
CURRENT_PAGE Faça a transição novamente para a página atual. Isso pode ser útil se você quiser que o agente repita algo.