Playbook parameters

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Note: The Agent Builder console still refers to playbooks as agents. This will be updated to playbook soon in the console.

Important: Conversational Agents (Dialogflow CX) playbooks and passing parameters between Conversational Agents (Dialogflow CX) flows and playbooks are documented here, but are currently restricted access. Passing parameters between Dialogflow agents is publicly available.

Playbooks can accept and emit context information using explicitly defined parameters. Parameters are used to store information about a conversation like user selections, results of actions, and so on. You can pass the values of these parameters between playbooks and flows.

Parameter declaration

You can define input parameters and output parameters.

When using the Agent Builder console, you can define parameters on the agent editor page.

When using the Dialogflow CX console, parameters are defined per playbook using the Parameters tab once you've created a playbook.

Parameters have a name, description, and one of the following types:

• String
• Number
• Boolean
• Tool-specific parameter type

You can also specify whether a parameter is a list.

Input parameters

Input parameters allow playbooks to use values passed from flows and other playbooks. For example, a playbook might receive a user's preferred name as a parameter and use it to thank the user personally, or it might receive an order identifier as a parameter and use it to retrieve order details using a tool.

Input parameters are defined per-playbook, and playbooks don't have visibility of other Dialogflow CX console parameter types by default. When a flow transitions to a playbook, page and session parameters are propagated to the playbook if the target playbook has an input parameter with the same name. To communicate information from a flow to a playbook during a transition, define playbook input parameters with the same name as a session or page parameter present before the transition.

Note: The default playbook does not accept input parameters. The default playbook serves as an entrypoint for user conversations, so it has no way to receive input parameters.

Create examples to control how the input parameter value should impact actions. For example, if an input parameter should affect how the agent refers to the user, create examples that define a value for the parameter and then use the same value in utterance actions within the example. See passing parameters for details.

Output parameters

Output parameters allow playbooks to emit information to be used by other flows or playbooks. For example, a playbook might collect an order number from a user and emit it through an output parameter, or a playbook might use a tool to book a flight and emit the confirmation number through an output parameter.

Create examples to control how the playbook should decide the value for each output parameter. For example, if an output parameter representing a confirmation number should derive its value from the output of a tool use, create examples where the output of the tool use matches the value of the playbook output parameter.

Passing parameters

Playbooks, unlike flows, do not support injecting parameter values with a particular syntax. Instead, playbooks rely on instructions and few-shot prompt examples to determine how parameter values should be used and how values should be decided when specifying parameter values.

Consider an agent designed for event ticket sales with the following playbooks:

1. A playbook named Ticket ordering which places orders using a tool named Ticket sales API.
   1. This playbook accepts an input parameter with type number and name event_id.
   2. The Ticket sales API tool expects a request including an event_id.
2. A playbook named Event selection which helps users select an event and then routes them to Ticket ordering with parameter event_id to purchase tickets.

In this example, to ensure that event_id is reliably passed from Event selection to Ticket ordering and from Ticket ordering to Ticket sales API, several examples are needed.

The Ticket ordering playbook should include multiple examples which:

• Have input parameter event_id specified with some realistic value, different in each example.
• Include a tool use action with a request body that includes the same realistic event_id value as specified in the input parameter.

The Event selection playbook should include multiple examples which:

• Include a user utterance where the user selects an event with some realistic event_id, different in each example.
• Include a playbook invocation of Ticket ordering which sets the event_id parameter to the same realistic event_id as decided by the user's selection.

In addition to adding examples, try adding specific instructions to the instructions, goal, or tool details explaining how parameters should be used. For example, playbook Ticket ordering includes the following instruction:

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

With the described examples and instructions present, the Event selection playbook correctly decides an event_id based on the user's selection, and passes it as an input parameter named event_id to the Ticket ordering playbook. Then, Ticket ordering passes the same event_id in the body of a request to the Ticket sales API. Playbooks depend on examples with distinct parameter values to help them infer how parameters should be used.