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 e assim por diante. É 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 um parâmetro e usá-lo para agradecer pessoalmente, ou pode receber um identificador de pedido como um 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 o playbook de destino 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 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, então ele não tem como 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 a forma como o agente se refere ao usuário, crie exemplos que definam um valor para o parâmetro e usem o mesmo valor em ações de declaração no exemplo. Consulte 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 a serem usadas por outros fluxos ou playbooks. Por exemplo, um playbook pode coletar um número de pedido de um usuário e emitir esse número por um parâmetro de saída, ou um playbook 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 precisar 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.

Transmitir parâmetros

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

Os playbooks, ao contrário dos fluxos, não oferecem suporte à injeção de valores de parâmetros com uma sintaxe específica. Em vez disso, os playbooks dependem de instruções e exemplos de comandos de poucas demonstrações para determinar como os valores de parâmetros devem ser usados e como os valores devem ser decididos ao especificar valores de parâmetros.

Playbook de rotina para fluxo

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

• Defina 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 em instruções e 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 em instruções e exemplos.

Playbook de tarefas para fluxo

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

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

Fluxo para playbook de tarefas

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

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

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

• Defina parâmetros de entrada de tarefas que compartilham o mesmo nome dos parâmetros de sessão no fluxo.
• Inclua o uso de parâmetros em instruções e 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 em instruções e exemplos.

Exemplo envolvendo ferramentas

Considere um agente projetado para vendas 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. Esse 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 forma 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:

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

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

• Incluam uma declaração do usuário em que ele seleciona um evento com algum event_id realista, diferente em cada exemplo.
• Incluam uma invocação de playbook de Ticket ordering que define 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, metas, 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 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, Ticket ordering transmite o mesmo event_id no corpo de uma solicitação para a Ticket sales API. Os playbooks dependem de exemplos com valores de parâmetros distintos para ajudar a inferir como os parâmetros devem ser usados.