Playbooks
Give an agent a goal and the outcomes that count as done, and let it find its own way there.
What you'll learn
How to write a playbook: a reusable, goal-driven skill with a prompt, tools and named outcomes. You use one when a conversation cannot be drawn as a straight line but you still need to control when the call moves on.
When to use one
There are three ways to get words out of an agent, from most to least controlled:
| Step | What you control |
|---|---|
| Scripted steps (Say, Ask, Confirm) | The exact words, in order. |
| A playbook | The goal and the outcomes. The model finds the path. |
| An AI reply | Nothing beyond the prompt: one free-form turn, no goal, no outcome. |
Use scripted steps for anything that must be said a specific way, such as disclosures and compliance lines. Use a playbook when the caller can take the conversation in several directions and you care about the outcome, not the wording.
Prerequisites
- A flow to use it in, or a plan to deploy it on its own. See Flow builder.
- Any tools the playbook should call, already registered.
Step 1: Create the playbook
Open Dashboard → Playbooks and create one. Fill in its parts:
Name lead_qualification
Description Qualify an inbound lead and book a demo if they are a fit
Instructions You are qualifying an inbound lead. Find out what they are
trying to solve, roughly how big their team is, and whether
they have a timeline. Be curious, not interrogative: one
question at a time, and react to what they say.
Tools lookup_account, book_demo
Outcomes Booked demo caller agreed to a demo
required: email, company
Not a fit wrong size or no need
Follow up later interested but not now
required: email| Part | What it does |
|---|---|
| Description | What the model reads to decide whether this playbook applies. Write it for the model, not your team. |
| Instructions | How to pursue the goal: tone, what to ask, what to avoid. This is the prompt, so the advice in Voice and turn-taking applies. |
| Tools | Which tools it may call while it works. Unlike an AI reply, a playbook can look things up and act mid-conversation. |
| Outcomes | How it can end. Each outcome becomes an exit on the canvas. Give each a plain description: that is how the model decides which one it reached. |
| Required variables | Per outcome. The playbook cannot exit through that outcome until these are captured. |
Required variables are enforced by the engine, not by asking the model nicely. If "Booked demo" requires an email and the model tries to finish without one, the exit is refused and the conversation continues. That is what makes a goal-driven step safe in a real call.
Step 2: Publish it
Publishing freezes a version. Flows keep the version they were deployed with, so improving a playbook never silently changes an agent that works.
Step 3: Use it
Two ways:
- In a flow: add a Playbook step and pick the playbook by name. Its outcomes appear as exits; connect each to what happens next. "Booked demo" might lead to a confirmation, "Not a fit" to a polite close.
- On its own: deploy the playbook directly as a one-step agent when it is the whole job.
Test it
A playbook is the least predictable step you can add, so test it most. In a dry run, be unhelpful, change your mind, and answer a different question than the one asked. Check it still lands on a sensible outcome. A replay can word things differently, so reset and run it a few times.
Common problems
| Problem | Fix |
|---|---|
| The agent improvises an ending | Add the unhappy outcomes too, such as "Not a fit" and "Wants a human". |
| The call never moves on | An outcome requires a value the caller cannot give. Require only what you truly need. |
| The playbook does too much | If it has eight outcomes, it is probably two playbooks with a Branch by intent step in front. |
Name outcomes as things that happened ("Booked demo"), not as next steps ("Send calendar invite").