Parâmetros do playbook

Os playbooks podem aceitar e emitir informações de contexto usando parâmetros definidos explicitamente. Os parâmetros são usados para armazenar informações sobre uma conversa, como seleções do usuário, resultados de ações etc. É possível transmitir os valores desses parâmetros entre playbooks e fluxos.

Declaração de parâmetro

É possível definir parâmetros de entrada (leitura) e parâmetros de saída (gravação).

Os parâmetros têm um nome, uma descrição e um dos seguintes tipos:

• String
• Número
• Booleano
• Tipo de parâmetro específico da ferramenta

Também é possível especificar se um parâmetro é uma lista.

Parâmetros de entrada (leitura)

Para cada playbook, é possível definir parâmetros de entrada, também chamados de parâmetros de leitura, que permitem que os playbooks usem valores transmitidos de fluxos e outros playbooks. Por exemplo, um playbook pode receber o nome preferido de um usuário como parâmetro e usá-lo para agradecer pessoalmente ou receber um identificador de pedido como parâmetro e usá-lo para recuperar detalhes do pedido usando uma ferramenta.

Os parâmetros de entrada são definidos por playbook, e os playbooks não têm visibilidade de outros tipos de parâmetros do console do Dialogflow CX por padrão. Quando um fluxo faz a transição para um playbook, os parâmetros de página e sessão são propagados para o playbook se ele tiver um parâmetro de entrada com o mesmo nome. Para comunicar informações de um fluxo para um playbook durante uma transição, defina parâmetros de entrada do playbook com o mesmo nome de um parâmetro de sessão ou de página presente antes da transição.

Observação: o playbook padrão não aceita parâmetros de entrada. O playbook padrão serve como um ponto de entrada para conversas com usuários, portanto, não pode receber parâmetros de entrada.

Crie exemplos para controlar como o valor de parâmetro de entrada deve afetar as ações. Por exemplo, se um parâmetro de entrada afetar como o agente se refere ao usuário, crie exemplos que definam um valor para o parâmetro e use o mesmo valor em ações de enunciado no exemplo. Consulte como transmitir parâmetros para mais detalhes.

Parâmetros de saída (gravação, retorno)

Para cada playbook, é possível definir parâmetros de saída, também chamados de parâmetros de gravação e parâmetros de retorno, que permitem que os playbooks emitam informações para serem usadas por outros fluxos ou playbooks. Por exemplo, um playbook pode coletar um número de pedido de um usuário e emiti-lo por um parâmetro de saída, ou pode usar uma ferramenta para reservar um voo e emitir o número de confirmação por um parâmetro de saída.

Crie exemplos para controlar como o playbook deve decidir o valor de cada parâmetro de saída. Por exemplo, se um parâmetro de saída que representa um número de confirmação precisa derivar o valor da saída de um uso de ferramenta, crie exemplos em que a saída do uso da ferramenta corresponda ao valor do parâmetro de saída do playbook.

Como transmitir parâmetros

Observação: um playbook de tarefa não pode chamar um playbook de rotina. Portanto, esse cenário de transmissão de parâmetros não é descrito abaixo.

Ao contrário dos fluxos, os playbooks não aceitam a injeção de valores de parâmetro com uma sintaxe específica. Em vez disso, os playbooks usam instruções e exemplos de comandos de poucos disparos para determinar como os valores de parâmetro devem ser usados e como os valores devem ser decididos ao especificar valores de parâmetro.

Playbook de rotina para fluxo

Para transmitir parâmetros de um playbook de rotina para um fluxo:

• Defina os parâmetros de gravação para o playbook de rotina. Esses parâmetros vão se tornar parâmetros de sessão.
• Os fluxos podem usar os parâmetros de sessão.
• Inclua o uso de parâmetros nas instruções e nos exemplos.

Fluxo para playbook de rotina

Para transmitir parâmetros de um fluxo para um playbook de rotina:

• Os fluxos gravam os parâmetros de sessão.
• Defina parâmetros de leitura para o playbook de rotina com os mesmos nomes.
• Inclua o uso de parâmetros nas instruções e nos exemplos.

Playbook de tarefas para fluxo

Para transmitir parâmetros de um playbook de tarefa para um fluxo:

• Nas configurações do fluxo, defina parâmetros de entrada com os mesmos nomes.
• Inclua o uso de parâmetros nas instruções e nos exemplos.

Fluxo para playbook de tarefas

Para transmitir parâmetros de um fluxo para um playbook de tarefa pai:

• Nas configurações do fluxo, defina os parâmetros de retorno.
• Inclua o uso de parâmetros nas instruções e nos exemplos.

Para transmitir parâmetros de um fluxo para um playbook de tarefas filho:

• Defina parâmetros de entrada de tarefa que compartilhem o mesmo nome dos parâmetros de sessão no fluxo.
• Inclua o uso de parâmetros nas instruções e nos exemplos.

Playbook de rotina para playbook de tarefas

Para transmitir parâmetros de um playbook de rotina para um playbook de tarefas:

• Defina parâmetros de entrada para o playbook de tarefas com os mesmos nomes.
• Inclua o uso de parâmetros nas instruções e nos exemplos.

Exemplo com ferramentas

Considere um agente projetado para venda de ingressos de um evento com os seguintes playbooks de tarefas:

1. Um playbook chamado Ticket ordering que faz pedidos usando uma ferramenta chamada Ticket sales API.
   1. Este playbook aceita um parâmetro de entrada com o tipo number e o nome event_id.
   2. A ferramenta Ticket sales API espera uma solicitação que inclua um event_id.
2. Um playbook chamado Event selection que ajuda os usuários a selecionar um evento e os direciona para Ticket ordering com o parâmetro event_id para comprar ingressos.

Neste exemplo, para garantir que event_id seja transmitido de maneira confiável de Event selection para Ticket ordering e de Ticket ordering para Ticket sales API, vários exemplos são necessários.

O playbook Ticket ordering precisa incluir vários exemplos que:

• Ter o parâmetro de entrada event_id especificado com algum valor realista, diferente em cada exemplo.
• Inclua uma ação de uso de ferramenta com um corpo de solicitação que inclua o mesmo valor realista de event_id especificado no parâmetro de entrada.

O playbook Event selection precisa incluir vários exemplos que:

• Inclua uma fala em que o usuário seleciona um evento com algum event_id realista, diferente em cada exemplo.
• Inclua uma invocação de playbook de Ticket ordering que defina o parâmetro event_id como o mesmo event_id realista decidido pela seleção do usuário.

Além de adicionar exemplos, tente adicionar instruções específicas às instruções, meta ou detalhes da ferramenta explicando como os parâmetros devem ser usados. Por exemplo, o playbook Ticket ordering inclui a seguinte instrução:

- Use parameter event_id to send a buy_tickets request with ${TOOL: Ticket sales API}

Com os exemplos e as instruções descritos, o playbook Event selection decide corretamente um event_id com base na seleção do usuário e o transmite como um parâmetro de entrada chamado event_id para o Ticket ordering playbook. Em seguida, o Ticket ordering transmite o mesmo event_id no corpo de uma solicitação para o Ticket sales API. Os playbooks dependem de exemplos com valores de parâmetro distintos para ajudar a inferir como os parâmetros devem ser usados.