Overview
A Playbook is a set of instructions your agent uses to handle a specific conversation task. You define the goal, explain how to handle the conversation, and add any tools it needs. The Playbook can then ask follow-up questions and use those tools to work toward the goal.
Examples of when to use Playbooks
Use a Playbook for a task where the conversation needs to adapt to the customer’s answers or to information returned by a tool. For example, you could configure a Playbook to:
- Book an appointment: ask which service the customer needs, collect their details, and use a booking tool to submit the request.
- Check an order: collect an order number or email, look up the order, and explain the status and delivery information returned by your tool.
- Qualify a lead: ask about the customer’s needs and collect the details your sales team needs for follow-up.
- Handle a support request: ask clarifying questions, find relevant information, and create a support ticket when further help is needed.
If the task needs a defined sequence of steps, consider whether a Workflow is a better fit:
How Playbooks work
Understand direct agent use and the alternative Workflow path.
Directly from the agent
Playbooks are most often used directly by the agent. The agent uses the Playbook’s trigger to decide when it fits a customer’s request, such as checking an order’s status or booking an appointment.
Once active, the Playbook follows its own instructions, asks for the information it needs, and uses its available tools to work toward the goal. It can ask follow-up questions and adapt to customer input and tool results across multiple turns. Keep the operational guidance it needs in the Playbook’s own instructions.
From a Workflow
A Workflow can also call a Playbook through a Playbook step when part of a defined process needs a flexible conversation. Configured exit conditions provide paths to the Workflow’s connected next steps.
These Workflow exit conditions do not apply when the agent calls the Playbook directly.
How to use Playbooks
Start from the Agent tab with the agent you want to configure. The captures below use the Appointment booking Playbook.
Add or create a Playbook
From the Agent tab, click + beside Playbooks. Select an existing Playbook or create a new one.
Name the Playbook and add a trigger
Name the Playbook at the top of the editor. In Trigger, describe when the agent should use it and what it should do.
Write the instructions
Write or generate the instructions in the Playbook editor. Include the goal, the steps to follow, and when to use each tool. Playbooks added from the Agent tab are automatically attached to the agent.
Add tools
Use the Tools panel on the right to add the integrations, APIs, MCPs, functions, or system tools the Playbook needs. Give each tool a clear name and trigger.
Run and refine the Playbook
Return to the Agent tab, then click Run or press Shift + R. Send a message that triggers the Playbook. Review the conversation, then refine the instructions and tool triggers if the behavior does not match the goal.
When the agent enters the intended Playbook and follows its instructions, continue with the capability details below to refine its configuration.
Triggering Playbooks
Control when your agent selects a Playbook for a customer request.
The agent uses the Playbook’s trigger to decide whether it fits a customer’s request. Give the Playbook a short name that identifies its task, and use the trigger to describe when it should be used and what it should accomplish.
From the Agent tab, open the Playbook. Edit its name at the top of the editor and its Trigger above the instructions. Keep the detailed conversation steps and tool handling in the Playbook’s instructions; the trigger summarizes when to start that task.
Check Playbook triggering
With the Playbook attached to your agent and its entry requirements met, return to the Agent tab and click Run or press Shift + R. Try a request within the trigger’s scope, another wording of the same task, and a neighboring request that belongs elsewhere. Check which Playbook starts and whether that matches the intended task.
If selection is unexpected, compare the message with this trigger and with any other Playbooks that describe similar requests. Refine their scope and test again. Entry conditions and required variables can keep a Playbook unavailable even when the request fits its trigger; configure those in Entry requirements.
A Workflow calls a Playbook differently: when it reaches a Playbook step, it starts the Playbook selected on that step. Configure that explicit call in the Workflow rather than relying on a customer message to select the Playbook.
Appointment booking trigger example
Copy a booking trigger and compare relevant and neighboring requests.
For the Appointment booking example shown above, the name and trigger are:
Name: Appointment booking
Trigger: Use when a client wants to book an appointment.
Collect their service, preferred time, and contact details,
then submit a request for the studio to confirm.This trigger identifies a booking request and summarizes the intended outcome: submitting a request for the studio to confirm. The instructions contain the detailed booking flow.
Use these messages to evaluate this sample trigger. These are intended outcomes for the example; verify them in your agent.
Triggering Playbooks best practices
Write focused triggers that distinguish the tasks your Playbooks handle.
- Describe a recognizable request. Say when the customer needs this Playbook, rather than giving a broad instruction such as “Help the customer.”
- State the task it should complete. Summarize the outcome, keeping the full procedure in the instructions.
- Make neighboring tasks distinct. If you have separate Playbooks for bookings, cancellations and rescheduling, describe the request each one handles.
Instructions
Define the Playbook’s goal and guide how it handles the conversation.
Specify the information to collect, when to use each tool, and how to handle missing or ambiguous results. Include the operational guidance the Playbook needs in its own instructions; agent-level routing instructions are no longer in context while it is active. The global prompt continues to supply identity, tone and guardrails on every turn. Compare instruction scopes.
The editor supports headings, lists, steps, and resource references. Pasted code blocks, tables, and images lose their formatting; use the supported editor blocks for instructions.
Order-status instructions
Adapt a complete prompt and check its expected outcomes.
This illustrative configuration assumes you have added an Order Lookup tool that returns order details. Adapt the tool name and available result fields to your own integration.
# Goal
Give the customer an accurate update on their existing order.
# Look up the order
Ask for the order number or the email used at checkout.
Use Order Lookup before giving an order-status update.
If there are multiple matches, share the item names and order
dates and ask which order the customer means.
If there is no match, confirm the details and try again.
If the order still cannot be found, offer a support handoff.
# Share the result
Share the item name, order status, and delivery date when
those fields are available in the lookup result.
Do not invent a status or delivery date that was not returned.With one matching order, the intended response is a status update based on that result. Multiple matches require a clarifying question; a missing order requires checking the details before offering a handoff. Test those cases with your configured tool.
Instructions best practices
Write clear goals and guidance for incomplete or ambiguous information.
Instruction formatting and references
Review supported formatting, variables, and missing references.
Fix a missing reference
A Missing reference warning means the referenced resource is no longer available to the agent. Check whether it was deleted or removed from the agent’s tools, then select a replacement or recreate it.
See Markdown shortcuts and resource references for the supported editor operations.
Tools
Give the Playbook the tools it needs to complete its goal.
Give each tool a name and trigger describing both its action and when to use it. Add and configure the tool before referring to it in the instructions. Function tools use the supported JavaScript input/output contract.
Choose a precise tool trigger
Compare two descriptions of the same order lookup.
In the example below, you configure an Order Lookup tool before referring to it in the instructions.
A broad trigger gives little information about when to choose a tool. The more specific version below names the request that should cause the lookup.
Look up orders.Look up an existing order when the customer asks about its
status or delivery date, after collecting their order
number or checkout email.Tools best practices
Clarify tool selection, coordinate calls, and check returned values.
- Describe the action and the situation. Give the tool a specific name and describe both what it does and when to use it. Compare descriptions when several tools could fit the same request, so their intended roles are clear.
- Explain input collection and ordering in Instructions. State which information to collect before calling a tool, how calls depend on earlier results, and how to handle those results. This keeps the tool’s description focused on selection while the Instructions explain the surrounding conversation.
- Test the tool independently. Use representative inputs and inspect the returned values before depending on them in a conversation. You can run saved tools independently; then test how the Playbook uses the result.
Function inputs, outputs, and runtime rules
Check the JavaScript contract used by a Playbook’s functions.
Check a failing function
Run the function with test inputs and inspect its outputs and logs. Check declared input/output names, supported JavaScript, and the returned object before testing the conversation again.
Use the Function tool reference for the exact entry point and return shape. Other tool types keep their own contracts: API tools and MCP tools.
AI model
Choose the Playbook’s AI model and adjust its generation settings.
Playbooks inherit the agent’s model settings unless you override them for that Playbook. Open Model in the top-right corner of the Playbook editor to change its settings. Available controls depend on the selected model. Max tokens controls generated response length.
Model overrides and supported controls
Compare inherited settings with a Playbook-specific configuration.
For an illustrative order-support agent, keep a Service information Playbook on the inherited settings. In the Order status Playbook, select the same AI model and lower Temperature where the selected model supports it. Compare the same order-status requests before and after the change, including one matching order, multiple matches, and a missing order. This example demonstrates a Playbook-specific override; it does not prescribe a model or guarantee better results.
Supported model controls
AI model best practices
Make deliberate overrides and compare their effect on the same tasks.
- Start from the inherited settings. Override them when this Playbook has a specific need. State what you want to improve before comparing configurations; review the Instructions and tool triggers when the goal or tool selection is unclear.
- Change one setting at a time. Compare the same representative messages and tool-result scenarios before and after the change. Keeping the test cases consistent helps you assess which change affected the behavior.
- Review controls after changing models. Available settings depend on the selected model, and the editor can adjust values to supported choices. Check the resulting configuration before testing again rather than assuming the previous settings still apply.
Entry requirements
Set the conditions and variables required for the agent to call the Playbook.
Entry conditions and required entry variables apply when the agent routes directly to a Playbook. They do not apply when a Workflow calls it through a Playbook step. The entry condition must pass and every required entry variable must have a value before the agent can route to the Playbook.
Required entry values must be collected before this Playbook becomes available; the blocked Playbook cannot collect them itself.
Check blocked Playbook entry
Compare condition and variable states before direct routing.
This illustrative account-management setup assumes you have created is_authenticated and account_id variables and populated them before routing. Configure an entry condition requiring is_authenticated to be true, and make account_id a required entry variable.
Test each state through the agent. Calling the Playbook from a Workflow uses a different control path and does not exercise these entry checks.
If entry remains blocked, check the actual condition result and every required entry value, then inspect the earlier conversation or process that supplies them.
Exit conditions
Define when the Playbook returns control to a Workflow.
Exit conditions apply when the Playbook runs through a Playbook step inside a Workflow. They are ignored when the agent triggers the Playbook directly. Any variables required by an exit condition must have values before that exit can trigger. Connect each exit to the Workflow step that should run next.
Continue a Workflow after collecting a return reason
Connect a completed conversation outcome to the next step.
A returns Workflow can call a Playbook to ask follow-up questions until the customer’s return reason is clear. A configured exit condition then leads to the Workflow’s connected eligibility-check step.
Here the Workflow owns the fixed eligibility process while the Playbook handles the flexible conversation within it. You configure the Workflow and exit condition for this scenario; it is not a built-in returns process. See how a Playbook returns control to a Workflow.
For an illustrative configuration, create a return_reason variable and an exit named Return reason collected. Require that variable on the exit and connect the exit to your Workflow’s eligibility-check step. Test that an incomplete reason does not satisfy the exit, then collect a reason and check the connected continuation.
Exit conditions best practices
Define clear completion outcomes and verify the connected continuation.
- Name an observable completion outcome. Make the exit’s purpose clear from its name and condition, so you can tell what must be achieved before the Workflow should continue.
- Require the data the next step needs. Choose exit variables based on the information the connected continuation will use. Review those requirements alongside the next step so completion leaves it with the necessary values.
- Test each connected exit with complete and missing values. Check that the intended completion takes its connected path, that missing required data prevents that exit, and that the expected next Workflow step runs.
Troubleshoot Workflow continuation
Check required exit data, connections, and per-turn settings.
See Playbook-step configuration for the Workflow controls and how control returns for exit-path behavior.
Next steps
- Explore agent tools to connect the Playbook to your services.
- Call a Playbook from a Workflow when it forms part of a fixed process.