Parâmetros do playbook

Os playbooks aceitam e emitem informações de contexto usando parâmetros definidos explicitamente. Os parâmetros armazenam informações da conversa, como seleções do usuário e resultados de ações. É 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 acesso a 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 os 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 porque serve como um ponto de entrada para conversas com usuários e não tem como recebê-los.

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 use o mesmo valor nas ações de enunciado do exemplo. Para mais informações, consulte Como transmitir parâmetros.

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 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 os playbooks determinam 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 deriva o valor de uma saída de uso de ferramenta, crie exemplos em que a saída da ferramenta corresponda ao valor do parâmetro de saída do playbook.

Como transmitir parâmetros

Observação: como um playbook de tarefa não pode chamar um playbook de rotina, esse cenário de transmissão de parâmetros não é descrito nas seções a seguir.

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 dependem de instruções e exemplos de comandos de poucos disparos para determinar como os valores de parâmetro devem ser usados e decididos.

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, que se tornam parâmetros de sessão quando o playbook de rotina é concluído.
• Use os parâmetros de sessão nos fluxos.
• 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:

• Escreva os parâmetros de sessão do fluxo.
• 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 o playbook de tarefas

Para transmitir parâmetros de um fluxo para um playbook de tarefas 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 da tarefa no playbook da tarefa que tenham 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 usando os mesmos nomes.
• Inclua o uso de parâmetros nas instruções e nos exemplos.

Exemplo envolvendo ferramentas

Suponha que um agente seja projetado para a venda de ingressos de um evento com os seguintes playbooks de tarefas:

• Um playbook chamado Ticket ordering que faz pedidos usando uma ferramenta chamada Ticket sales API.
  • Este playbook aceita um parâmetro de entrada do tipo number chamado event_id.
  • A ferramenta Ticket sales API espera uma solicitação que inclua um event_id.
• 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, você precisa de vários exemplos.

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

• Especifique o parâmetro de entrada event_id com um valor realista que seja 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 do usuário em que um evento com um event_id realista seja selecionado, com um ID 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 determinado pela seleção.

Além de adicionar exemplos, adicione instruções específicas às instruções, objetivo ou detalhes da ferramenta explicando como os parâmetros devem ser usados.

Por exemplo, o playbook Ticket ordering pode incluir 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 playbook Ticket ordering. 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 são usados.