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 as 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 ES. Acesse a documentação e abra o Console (em inglês). As instruções abaixo referem-se ao uso do Console. Para acessar dados de ações e parâmetros:

1. Acesse o Console do Dialogflow ES.
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.

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 de criação de um agente, é possível definir esse campo para qualquer texto que 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, chamado de 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 uma sala na terça-feira", em que "terça-feira" é anotada.

• Obrigatório: marque esta caixa se o parâmetro for obrigatório para que a intent seja concluída. 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 for necessário 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 mouse 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ídos separadamente:

Depois de anotar pelo menos duas palavras ou frases com o mesmo parâmetro em uma única frase de treinamento, a opção É lista será ativada automaticamente. Se você desativar essa opção, mas mantiver a mesma anotação, É lista será verificado automaticamente mais uma vez quando você abrir a página com essa anotação.

Em agentes multilíngues, a opção É lista não é específica de linguagem.

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 em texto que é 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, use 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âmetros para datas ambíguas

Quando um parâmetro é associado à entidade do sistema @sys.date e o usuário final fornece uma data parcial (não especificando mês, dia e ano), o Dialogflow fará a correspondência com a data mais próxima no futuro. de dados. No entanto, você também pode recuperar variações dessa data.

É possível recuperar a correspondência parcial explícita, em que o Dialogflow substitui a parte desconhecida por Us usando o seguinte formato:

$parameter-name.partial

É possível recuperar a data mais próxima no passado usando o seguinte formato:

$parameter-name.recent

Por exemplo, se a data de hoje for 11 de agosto de 2021, o nome do parâmetro será date e o usuário disser "13 de agosto":

Referência de parâmetros	Valor resolvido
$date	2021-08-13
$date.partial	UUUU-08-13
$date.recent	2020-08-13

Referência de parâmetro de 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, referencie 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 referenciar 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 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 prompts de parâmetros.

Veja alguns exemplos dos efeitos dessa ordem para uma expressão de usuário final como "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.

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.

Por exemplo, considere que o agente de loja de roupas tem uma intent com parâmetros obrigatórios para:

• 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á os dados fornecidos e continuará solicitando os dados ausentes. 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

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

Quando um agente é criado com o console, passar o mouse sobre um parâmetro revelará um ícone de reordenar à direita. 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 parâmetros obrigatórios antes do prompt. Por exemplo, se o parâmetro color estiver antes do parâmetro quantity, use o seguinte aviso 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.

Se você estiver usando a API, o campo DetectIntentResponse.queryResult.cancelsSlotFilling será definido como true quando o preenchimento de slot for cancelado. Para mais informações, consulte a documentação detectIntent do tipo Sessions.