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

Você também pode 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 pode 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 a 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.

Crie exemplos para controlar como o valor do 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 use o mesmo valor em ações de expressão no exemplo. Consulte transmissão de 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 emitir esse número por um parâmetro de saída. Ou ele 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 de ferramenta corresponda ao valor do parâmetro de saída do playbook.

Transmissão de parâmetros

Os playbooks, ao contrário dos fluxos, não aceitam a inserção de valores de parâmetros com uma sintaxe específica. Em vez disso, os playbooks usam instruções e exemplos de comandos de poucas tentativas para determinar como os valores de parâmetros devem ser usados e 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.

Manual de transição do fluxo para a 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 tarefa 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 o playbook de tarefas

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

• 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 secundárias:

• Defina parâmetros de entrada de tarefa 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 tarefa

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

• 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 eventos 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 encaminha 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, são necessários vários exemplos.

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

• Tenha o parâmetro de entrada event_id especificado com um 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 event_id realista especificado no parâmetro de entrada.

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

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

Além de adicionar exemplos, tente incluir instruções específicas nas 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 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 o 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.