Playbook parameters

Playbooks accept and emit context information using explicitly defined parameters. Parameters store conversation information, such as user selections and action results. You can pass the values of these parameters between playbooks and flows.

Parameter declaration

You can define input (read) parameters and output (write) parameters.

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 (read) parameters

For each playbook, you can define input parameters, also called read parameters, that let playbooks 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 access to 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.

Create examples to control how the input parameter value should affect 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. For more information, see passing parameters.

Output (write, return) parameters

For each playbook, you can define output parameters, also called write parameters and return parameters, that let playbooks 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 playbooks determine the value for each output parameter. For example, if an output parameter representing a confirmation number derives its value from a tool use output, create examples where the tool output matches the value of the playbook output parameter.

Passing parameters

Playbooks, unlike flows, don't 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 decided.

Routine playbook to flow

To pass parameters from a routine playbook to a flow:

• Define write parameters for the routine playbook, which become session parameters when the routine playbook completes.
• Use the session parameters in flows.
• Include parameter usage in instructions and examples.

Flow to routine playbook

To pass parameters from a flow to a routine playbook:

• Write the session parameters from the flow.
• Define read parameters for the routine playbook with the same names.
• Include parameter usage in instructions and examples.

Task playbook to flow

To pass parameters from a task playbook to a flow:

• In the flow settings, define input parameters of the same names.
• Include parameter usage in instructions and examples.

Flow to task playbook

To pass parameters from a flow to a parent task playbook:

• In the flow settings, define return parameters.
• Include parameter usage in instructions and examples.

To pass parameters from a flow to a child task playbook:

• Define task input parameters in the task playbook that share the same name as session parameters in the flow.
• Include parameter usage in instructions and examples.

Routine playbook to task playbook

To pass parameters from a routine playbook to a task playbook:

• Define input parameters for the task playbook using the same names.
• Include parameter usage in instructions and examples.

Sample involving tools

Suppose that an agent is designed for event ticket sales with the following task playbooks:

• A playbook named Ticket ordering that places orders by using a tool named Ticket sales API.
  • This playbook accepts an input parameter of type number named event_id.
  • The Ticket sales API tool expects a request including an event_id.
• A playbook named Event selection that helps users select an event and then routes them to Ticket ordering with the 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, you need several examples.

The Ticket ordering playbook should include multiple examples that:

• Specify the input parameter event_id with a realistic value that differs 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 that:

• Include a user utterance where an event with a realistic event_id is selected, with a different ID in each example.
• Include a playbook invocation of Ticket ordering that sets the event_id parameter to the same realistic event_id as determined by the selection.

Besides adding examples, add specific instructions to the instructions, goal, or tool details explaining how parameters should be used.

For example, the Ticket ordering playbook can include 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 are used.