Ações e parâmetros

Nesta página, você vê as configurações de ações e parâmetros para intents e como elas são usadas quando intents são correspondidas no ambiente de execução.

Onde encontrar esses dados

Ao criar um agente, o mais comum é usar o console do Dialogflow. Acesse a documentação e abra o console. As instruções abaixo se concentram no uso do Console. Para acessar dados de ações e parâmetros:

  1. Acesse o Console do Dialogflow (em inglês).
  2. Selecione um agente.
  3. Selecione Intents no menu da barra lateral à esquerda.
  4. Selecione uma intent.
  5. Role até a seção Ação e parâmetros.

Captura de tela dos campos de ação e parâmetros

Se você estiver usando a API em vez do console para criar um agente, consulte a referência de intents. Os nomes de campo da API são semelhantes aos nomes de campo do Console. As instruções abaixo destacam as diferenças importantes entre o Console e a API.

Ações

O campo de ação é um campo de conveniência simples que ajuda na execução de lógica no serviço.

No momento da criação de um agente, é possível definir esse campo para qualquer texto que você achar útil.

Quando há correspondência de uma intent no ambiente de execução, o Dialogflow fornece o valor de ação para sua solicitação de webhook de fulfillment ou a resposta de interação da API. É possível usá-lo para acionar a lógica específica no serviço.

Parâmetros

Quando uma intent é correspondida no ambiente de execução, o Dialogflow fornece os valores extraídos da expressão do usuário final como parâmetros. Cada parâmetro tem um tipo, conhecido como tipo de entidade, que dita exatamente como os dados são extraídos. Ao contrário da entrada bruta do usuário final, os parâmetros são dados estruturados que podem ser facilmente usados para executar uma lógica ou gerar respostas.

Ao criar um agente, você controla como os dados são extraídos anotando partes das frases de treinamento e configurando os parâmetros associados.

A lista a seguir mostra os campos de uma configuração de parâmetros. Os exemplos mostram a frase de treinamento "reservar um quarto na terça-feira", em que "terça-feira" é anotada.

  • Obrigatório: marque esta caixa se o parâmetro for obrigatório para a conclusão da intent. Consulte a seção Preenchimento de slot com os parâmetros obrigatórios a seguir.
  • Nome do parâmetro: um nome que identifica o parâmetro. Exemplo: date.
  • Entidade: o tipo de entidade associado ao parâmetro. Exemplo: @sys.date.
  • Valor: na maioria dos casos, isso é definido como uma referência de parâmetro como $parameter-name, que é usada como um marcador para o valor extraído no ambiente de execução. No entanto, esse campo também pode ser usado para selecionar valores alternativos. Consulte a seção Valores e referências de parâmetro abaixo. Exemplo: $date.
  • É lista: marque esta caixa se for preciso que os valores retornem como uma lista. Consulte a seção Parâmetros de lista a seguir.
  • Prompts: perguntas que o agente fará ao usuário final, se esse parâmetro não tiver sido fornecido. Este campo é usado apenas quando o campo Obrigatório está marcado. Consulte a seção Preenchimento de slot com os parâmetros obrigatórios a seguir.
  • Valor padrão: este é o valor padrão do parâmetro quando o usuário final não fornece um. Para alterar o valor padrão com o console, passe o cursor sobre a linha do parâmetro e clique no menu à direita.

Quando há correspondência de uma intent no ambiente de execução, o Dialogflow fornece os dados do parâmetro para sua solicitação de webhook de fulfillment ou a resposta de interação da API. Eles são fornecidos como um mapeamento de nomes para valores de parâmetros.

Ao criar um agente, as respostas podem incluir valores de parâmetro. Consulte Valores e referências de parâmetros abaixo.

Parâmetros de lista

Quando um agente é criado com o console, marcar a opção É lista configura o parâmetro como uma lista. As listas podem conter vários elementos. Por exemplo, um agente de ordem de produção pode esperar as seguintes expressões de usuário final:

  • “Quero maçãs”
  • “Quero maçãs e laranjas”
  • “Quero maçãs, laranjas e bananas”

Ao anotar frases de treinamento com parâmetros de lista, elas podem conter um ou mais exemplos de parâmetros, que precisam ser incluídas separadamente:

Captura de tela da anotação do parâmetro de lista.

Valores e referências de parâmetros

Referências de parâmetro são variáveis que armazenam valores de parâmetro extraídos no ambiente de execução. Ao criar um agente, é possível usar referências de parâmetro em respostas de intent, prompts de parâmetro e o campo do parâmetro Valor.

Por exemplo, use $parameter-name em uma resposta de intent. Quando o Dialogflow responde ao usuário, ele substitui essa referência de parâmetro pelo valor do parâmetro extraído no ambiente de execução. Isso é útil para recapitular as informações fornecidas pelo usuário final. Por exemplo, a resposta da intent poderia ser: "Ok, reservei um quarto para você para $date".

Referência de parâmetro básica

Para fazer referência a um valor de parâmetro extraído pela entidade associada, use o seguinte formato:

$parameter-name

Por exemplo, se o nome do parâmetro for date, faça referência a ele como $date.

Referência de parâmetro para um valor original

Quando há correspondência do texto com uma entidade específica, muitas vezes ele é convertido no formato de texto que for mais conveniente para o processamento. Por exemplo, a palavra "maçãs" em uma expressão de usuário final pode ser extraída como "maçã" para uma entidade de fruta. Para fazer referência a um valor de parâmetro exatamente como ele foi escrito ou falado pelo usuário final, utilize o seguinte formato:

$parameter-name.original

Por exemplo, se o nome do parâmetro for date, faça referência ao valor original como $date.original.

Referência de parâmetro para uma entidade composta

Entidades compostas são entidades que contêm outras subentidades. Para fazer referência ao valor da subentidade de um parâmetro, use o seguinte formato:

$parameter-name.sub-entity-name

Por exemplo, se o nome do parâmetro for move e o nome da subentidade for direction, faça referência o valor da subentidade como $move.direction.

Referência de parâmetro para um contexto ativo

Os contextos podem servir como armazenamento temporário para valores de parâmetro. Para fazer referência a um valor de parâmetro recebido de um contexto ativo, use o seguinte formato:

#context-name.parameter-name

Por exemplo, se o nome do parâmetro for room e reservation for um contexto ativo, será possível fazer referência ao valor do parâmetro como #reservation.room.

Referência de parâmetro para um parâmetro de evento

Para fazer referência a um parâmetro evento, use o seguinte formato:

#event-name.parameter-name

Por exemplo, se o nome do parâmetro for duration e o nome do evento for alarm, será possível fazer referência ao parâmetro do evento como #alarm.duration.

Campo "Valor" do parâmetro

As referências de parâmetro no campo Valor do parâmetro têm um significado especial. O conteúdo nesse campo determina o valor resolvido para $parameter-name em respostas à intent e às solicitações de parâmetro. O Dialogflow processa dados de parâmetros na seguinte ordem:

  1. Extraia o valor do parâmetro da expressão do usuário final usando a entidade associada.
  2. Resolva o conteúdo para o campo Valor do parâmetro.
  3. Definir $parameter-name ao conteúdo resolvido do campo Valor do parâmetro. Se o campo Valor não for definido como $parameter-name, o valor de $parameter-name será redefinido para outro item.
  4. Resolva o conteúdo das respostas às intents e solicitações de parâmetros.

Veja alguns exemplos dos efeitos dessa ordem para uma expressão de usuário final de "Quero comprar uma camisa pequena".

Local de referência do parâmetro Conteúdo configurado Conteúdo resolvido
Campo Valor do parâmetro $size P
Resposta da intent Você escolheu o tamanho: $size Você escolheu o tamanho: P
Local de referência do parâmetro Conteúdo configurado Conteúdo resolvido
Campo Valor do parâmetro $size.original pequeno
Resposta da intent Você escolheu o tamanho: $size Você escolheu o tamanho: pequeno
Local de referência do parâmetro Conteúdo configurado Conteúdo resolvido
Campo Valor do parâmetro $size P
Resposta da intent Você escolheu o tamanho: $size.original Você escolheu o tamanho: pequeno

Preenchimento de slot com os parâmetros obrigatórios

Quando um agente é criado, é possível marcar os parâmetros conforme necessário. Uma intent não está completa até que o usuário final forneça dados para cada um desses parâmetros obrigatórios.

Captura de tela dos campos de parâmetros obrigatórios

Quando há correspondência de uma intent no ambiente de execução, o agente do Dialogflow continua coletando informações do usuário final até que ele forneça dados para cada um dos parâmetros obrigatórios. Esse processo é chamado de preenchimento de slot.

O Dialogflow não envia uma solicitação de webhook de fulfillment até ter coletado todos os dados obrigatórios do usuário final, a menos que o webhook de preenchimento de slot esteja ativado.

O Dialogflow envia uma resposta de interação da API para cada etapa de preenchimento de slot. Para cada uma dessas respostas de preenchimento de slot, a intent e a ação serão as mesmas, e os parâmetros coletados até o momento serão fornecidos.

Ao criar um agente, você fornece prompts que ele usará para receber dados de parâmetro do usuário final. Também é possível fornecer variações de prompt. Assim, o agente não fará sempre a mesma pergunta.

Captura de tela de prompts de parâmetro

Por exemplo, imagine que o agente de loja de roupas tenha uma intent com parâmetros obrigatórios para estes itens:

  • tipo de roupa
  • quantidade
  • tamanho
  • cor

A conclusão de uma intent pode ser semelhante a esta:

Usuário: Eu gostaria de comprar uma camiseta.
Agente: Quantas você quer?
Usuário: Três.
Agente: Qual cor você quer?
Usuário: Preta.
Agente: Qual é o tamanho?
Usuário: Médio.
Agente: Entendi, três camisetas pretas tamanho médio.

Se o usuário final fornecer dados para mais de um parâmetro em uma única expressão, o Dialogflow coletará as informações disponibilizadas e continuará solicitando o que está faltando. Por exemplo, o usuário final pode dizer: "Eu gostaria de comprar três camisetas pretas". O Dialogflow perguntaria ao usuário qual o tamanho.

Como ordenar parâmetros

Ao criar um agente, é possível ordenar os parâmetros, o que determinará a ordem em que o agente solicitará os dados ausentes ao usuário final.

Ao criar um agente com o console, um ícone de reordenar aparecerá à direita quando você passar o cursor sobre um parâmetro. Para alterar a posição do parâmetro na lista, arraste esse ícone.

Referências de parâmetros em prompts

Ao criar um agente, é possível usar referências de parâmetro em prompts, mas apenas para aqueles que forem obrigatórios antes do prompt. Por exemplo, se o parâmetro color estiver antes do parâmetro quantity, use o seguinte prompt para o parâmetro quantity: How many $color t-shirts would you like to buy?

Cancelar o preenchimento do slot

Quando o usuário final diz uma frase de saída, como "Cancelar", "Parar", "Chega" etc., o agente responde com "Ok, cancelado" e limpa os contextos de preenchimento de slot.