Ações e parâmetros

Esta página descreve as definições de ações e parâmetros para intenções e como são usadas quando as intenções são correspondidas em tempo de execução.

Onde encontrar estes dados

Ao criar um agente, é mais comum usar a consola do Dialogflow ES (visite a documentação, abra a consola). As instruções abaixo focam-se na utilização da consola. Para aceder aos dados de ações e parâmetros:

1. Aceda à consola do Dialogflow ES.
2. Selecione um agente.
3. Selecione Intenções no menu da barra lateral esquerda.
4. Selecione uma intenção.
5. Desloque a página para baixo até à secção Ação e parâmetros.

Se estiver a criar um agente através da API em vez da consola, consulte a referência de intenções. Os nomes dos campos da API são semelhantes aos nomes dos campos da consola. As instruções abaixo realçam as diferenças importantes entre a consola e a API.

Ações

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

Ao criar um agente, pode definir este campo para qualquer texto que considere útil.

Quando uma intenção é correspondida no tempo de execução, o Dialogflow fornece o valor da ação ao pedido do webhook de processamento ou à resposta de interação da API. Pode ser usado para acionar uma lógica específica no seu serviço.

Parâmetros

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

Quando cria um agente, controla a forma como os dados são extraídos anotando partes das suas expressões de preparação e configurando os parâmetros associados.

A lista seguinte mostra os campos de uma configuração de parâmetros. São apresentados exemplos para a expressão de treino "book a room on Tuesday" (reservar um quarto na terça-feira), em que "Tuesday" (terça-feira) está anotado.

• Obrigatório: Selecione esta caixa se o parâmetro for obrigatório para que a intenção seja concluída. Consulte a secção Preenchimento de espaços com parâmetros obrigatórios abaixo.
• 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, isto é definido como uma referência de parâmetro, como $parameter-name, que é usado como um marcador de posição para o valor extraído no tempo de execução. No entanto, este campo também pode ser usado para selecionar valores alternativos. Consulte a secção Valores dos parâmetros e referências de parâmetros abaixo. Exemplo: $date.
• É lista: Selecione esta caixa se os valores deverem ser devolvidos como uma lista. Consulte a secção Listar parâmetros abaixo.
• Comandos: Perguntas que o agente faz ao utilizador final se este parâmetro não tiver sido fornecido. Este campo só é usado se o campo Obrigatório estiver selecionado. Consulte a secção Preenchimento de espaços com parâmetros obrigatórios abaixo.
• Valor predefinido: Este é o valor predefinido do parâmetro quando o utilizador final não fornece nenhum. Para alterar o valor predefinido com a consola, tem de passar o cursor do rato sobre a linha do parâmetro e clicar no menu à direita.

Quando uma intenção é correspondida no tempo de execução, o Dialogflow fornece dados de parâmetros ao seu pedido de webhook de processamento ou à resposta de interação da API. Estes são fornecidos como um mapeamento de nomes de parâmetros para valores de parâmetros.

Quando cria um agente, as suas respostas podem incluir valores de parâmetros. Consulte Valores dos parâmetros e referências sobre parâmetros abaixo.

Parâmetros da lista

Quando cria um agente com a consola, se selecionar a opção Is List, configura o parâmetro como uma lista. As listas podem conter vários elementos. Por exemplo, um agente de encomenda de produtos agrícolas pode esperar as seguintes expressões do utilizador final:

• "Quero maçãs"
• "Quero maçãs e laranjas"
• "Quero maçãs, laranjas e bananas"

Quando anota expressões de preparação com parâmetros de lista, as suas expressões podem conter um ou mais exemplos de parâmetros, e anota cada um separadamente:

Depois de anotar, pelo menos, duas palavras ou expressões com o mesmo parâmetro numa única expressão de preparação, a opção É lista é ativada automaticamente. Se desativar esta opção, mas mantiver a mesma anotação, a opção É lista é selecionada automaticamente novamente quando abrir a página com esta anotação.

Nos agentes multilingues, a opção Is List não é específica do idioma.

Valores de parâmetros e referências sobre parâmetros

As referências de parâmetros são variáveis que contêm valores de parâmetros extraídos no tempo de execução. Quando cria um agente, pode usar referências de parâmetros nas respostas de intenções, nos pedidos de parâmetros e no campo Valor do parâmetro.

Por exemplo, pode usar $parameter-name numa resposta de intenção. Quando o Dialogflow responde ao utilizador, substitui essa referência de parâmetro pelo valor do parâmetro extraído no tempo de execução. Isto é útil para resumir as informações fornecidas pelo utilizador final. Por exemplo, a resposta de intenção pode ter o seguinte aspeto: "OK. Reservei um quarto para si a $date".

Referência dos parâmetros básicos

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, pode fazer referência ao mesmo como $date.

Referência de parâmetro para um valor original

Quando o texto corresponde a uma entidade específica, é frequentemente convertido em texto mais conveniente para processamento. Por exemplo, a palavra "apples" (maçãs) numa expressão do utilizador final pode ser extraída como "apple" (maçã) para uma entidade de fruta. Para fazer referência a um valor de parâmetro exatamente como foi escrito ou dito pelo utilizador final, use o seguinte formato:

$parameter-name.original

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

Referência de parâmetros para datas ambíguas

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

Pode obter a correspondência parcial explícita, em que o Dialogflow substitui a parte desconhecida por Us usando o seguinte formato:

$parameter-name.partial

Pode obter 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 for date, e o utilizador 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 para uma entidade composta

As entidades compostas são entidades que contêm outras subentidades. Para fazer referência ao valor de uma 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, pode fazer referência ao valor da subentidade como $move.direction.

Referência de parâmetros para um contexto ativo

Os contextos podem servir como armazenamento temporário para valores de parâmetros. Para fazer referência a um valor de parâmetro obtido a partir 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, pode fazer referência ao valor do parâmetro como #reservation.room.

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

Para fazer referência a um parâmetro de 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, pode fazer referência ao parâmetro de evento como #alarm.duration.

Campo Valor do parâmetro

As referências de parâmetros no campo Valor do parâmetro têm um significado especial. O conteúdo neste campo determina o valor resolvido para$parameter-name em respostas de intenção e comandos de parâmetros. O Dialogflow processa os dados dos parâmetros pela seguinte ordem:

1. Extraia o valor do parâmetro da expressão do utilizador final através da entidade associada.
2. Resolva o conteúdo do campo Valor.
3. Defina$parameter-name para o conteúdo resolvido do campo de parâmetro Valor. Se o campo Valor não estiver definido como $parameter-name, isto repõe o valor de $parameter-name para outra coisa.
4. Resolva conteúdo para respostas de intenção e comandos de parâmetros.

Seguem-se alguns exemplos para ilustrar os efeitos desta ordenação para uma expressão do utilizador final "Quero comprar uma camisa pequena".

Localização de referência do parâmetro	Conteúdo configurado	Conteúdo resolvido
Campo Valor do parâmetro	$size	S
Resposta de intenção	Escolheu o tamanho: $size	Escolheu o tamanho: S

Localização de referência do parâmetro	Conteúdo configurado	Conteúdo resolvido
Campo Valor do parâmetro	$size.original	pequeno
Resposta de intenção	Escolheu o tamanho: $size	Escolheu o tamanho: pequeno

Localização de referência do parâmetro	Conteúdo configurado	Conteúdo resolvido
Campo Valor do parâmetro	$size	S
Resposta de intenção	Escolheu o tamanho: $size.original	Escolheu o tamanho: pequeno

Preenchimento de espaços com parâmetros obrigatórios

Quando cria um agente, pode marcar os parâmetros como obrigatórios. Uma intenção não está concluída até o utilizador final fornecer dados para cada um destes parâmetros obrigatórios.

Quando uma intenção é correspondida no tempo de execução, o agente do Dialogflow continua a recolher informações do utilizador final até que este tenha fornecido dados para cada um dos parâmetros necessários. Este processo é denominado preenchimento de espaços.

O Dialogflow não envia um pedido de webhook de processamento de encomendas até ter recolhido todos os dados necessários do utilizador final, a menos que a opção webhook para preenchimento de espaços esteja ativada.

O Dialogflow envia uma resposta de interação da API para cada passo do preenchimento de espaços. Para cada uma destas respostas de preenchimento de espaços, a intenção e a ação serão as mesmas, e os parâmetros recolhidos até agora serão fornecidos.

Quando cria um agente, fornece comandos que o agente vai usar para obter dados de parâmetros do utilizador final. Também pode fornecer variações de comandos, para que o agente não faça sempre a mesma pergunta.

Por exemplo, considere que o agente da sua loja de roupa tem uma intenção com parâmetros obrigatórios para:

• tipo de vestuário
• quantity
• tamanho
• cor

A conclusão de uma intenção pode ter o seguinte aspeto:

Utilizador: Quero comprar uma t-shirt.
Agente: quantos quer?
Utilizador: 3
Agente: Que cor quer?
Utilizador: Preto
Agente: Qual é o tamanho?
Utilizador: Medium
Agente: Compreendo. Foram três t-shirts pretas no tamanho M.

Se o utilizador final fornecer dados para mais do que um parâmetro numa única expressão, o Dialogflow recolhe os dados fornecidos e continua a pedir os dados em falta. Por exemplo, o utilizador final pode dizer "Quero comprar três t-shirts pretas". O Dialogflow pede o tamanho ao utilizador.

Parâmetros de ordenação

Ao criar um agente, pode ordenar os parâmetros, o que determina a ordem pela qual o agente pede ao utilizador final os dados em falta.

Quando cria um agente a partir da consola, se passar o cursor do rato sobre um parâmetro, é apresentado um ícone de reordenação à direita. Pode arrastar este ícone para alterar a posição do parâmetro na lista.

Referências sobre parâmetros em comandos

Ao criar um agente, pode usar referências de parâmetros em comandos, mas apenas para parâmetros obrigatórios antes do comando. Por exemplo, se o parâmetro color estiver antes do parâmetro quantity, pode usar o seguinte comando para o parâmetro quantity: How many $color t-shirts would you like to buy?

Cancele o preenchimento de horários

Quando o utilizador final diz uma expressão de saída, como "Cancelar", "Para", "Chega", etc., o agente responde com "OK, cancelado" e limpa os contextos de preenchimento de espaços.

Se estiver a usar a API, o campo DetectIntentResponse.queryResult.cancelsSlotFilling é definido como true quando o preenchimento de espaços é cancelado. Para mais informações, consulte a detectIntentdocumentação do tipo Sessions.