> For the complete documentation index, see [llms.txt](https://aibotkit-docs.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aibotkit-docs.gitbook.io/documentation/chatbot-editor/playbooks.md).
# BEHAVIOR: Playbooks
A **playbook** is how you want one particular kind of conversation handled, start to finish. Your agent recognises the situation and follows your steps.
Playbooks are goal-based: you describe the outcome you want and the route to get there, and your agent switches the playbook on by itself whenever a conversation matches it.
Open your agent, then go to **Behavior → Playbooks** in the left sidebar.
***
## Rules vs. playbooks — which do I need?
This is the most common question, and the difference is simple:
| | Applies | Best for |
| ---------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------ |
| [**Agent rules**](/documentation/chatbot-editor/instructions.md#agent-rules) | **Always**, in every conversation | Boundaries — "never quote a price", limits, policies |
| **Playbooks** | **Only when the situation matches** | Procedures — "how to qualify a project inquiry", "how to take a booking" |
If you find yourself writing a rule that starts with *"When a customer wants to…"*, you probably want a playbook. And the other way round: a limit that must hold no matter what belongs in Agent rules, not inside a playbook.
***
## Creating a playbook
Click **Add playbook**. You can start from a blank playbook, or from a template:
| Template | Handles |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| **Booking** | Scheduling, reservations, appointments, availability |
| **Quotation** | Price quotes and order estimates from a catalog, bulk or wholesale orders, and "send me a quote" requests |
| **FAQ** | Quick factual lookups — opening hours, location, a single policy or price point |
| **Blank playbook** | Anything else — you write the trigger and the steps yourself |
Templates are pre-filled examples. Open one and edit it to match how *your* business actually handles that conversation.
Every playbook has three fields:
**Name.** Just for you — your agent never sees it. "Event Lead Qualification", "Cancellation Help".
**Trigger.** One or two sentences telling your agent *when* to use this playbook:
> Use when a visitor is asking about a new project — a website, a redesign, an online store — and wants to know if we can help. Not for visitors asking about an existing project.
If you have more than one playbook, make each trigger clearly different from the others. Your agent chooses between playbooks by reading the triggers, so overlapping triggers mean the wrong one fires.
**Content.** The instructions themselves — see below.
***
## What goes in a playbook
The quality of your playbook directly affects the quality of your agent. Vague instructions produce inconsistent behavior; a clear structure produces an agent that gets things done.
Write it the way you'd brief a new member of staff. A complete playbook has five parts:
* **GOAL** — what the conversation should achieve, including exactly what counts as "qualified" or "done".
* **STEPS** — the route, in order, with every check placed at the step where the answer arrives.
* **EDGE CASES** — what to do when the visitor refuses something or wanders off-script.
* **EXITS** — the ways the conversation is allowed to end, spelled out. Every conversation ends in exactly one of them.
* **EXAMPLES** — one or two correct/incorrect replies showing the mistakes that matter most.
One thing a playbook should **not** contain: a rules section. Your limits and policies (a minimum budget, "never estimate a price") go under **Instructions → Agent rules** as **Hard rules** — the playbook's steps *reference* the limits, the Hard rules *enforce* them (more on why below).
Here's a complete example — a lead qualification playbook at a web design agency:
> **GOAL**\
> Turn project inquiries into qualified leads for the sales team. A lead is QUALIFIED only when ALL of these are known: what the visitor needs, a budget of $2,000 or more, their timeline, and their name + email captured through the contact form.
>
> **STEPS (in this order)**
>
> 1. What they need — a new website, a redesign, or an online store.
> 2. About the project — what the site is for and what matters most to them. Rough understanding is enough; detailed scoping happens on the consultation call.
> 3. Budget — ask their budget range.
> 4. BUDGET GATE — check the budget NOW, before anything else:
> * Under $2,000 → go to DISQUALIFIED EXIT.
> * Unsure about budget → continue; the team will discuss it on the call.
> * $2,000 or more → continue.
> 5. Timeline — when they'd like to start.
> 6. CAPTURE — only after the BUDGET GATE (step 4) has passed: say the team will share an exact estimate on a consultation call, and show the contact form. This is the only step where the form is used, and it is never used before the gate. Never say details are saved or passed to the team unless the form was actually submitted.
>
> **EDGE CASES**
>
> * If the visitor declines the contact form, don't push — share our email address from the knowledge base and end warmly.
> * If the visitor asks an unrelated question mid-flow (past work, the tech we use), answer it from the knowledge base, then continue from the pending step.
>
> **EXITS (the conversation ends in exactly one of these)**
>
> * QUALIFIED EXIT — after the form is submitted: confirm in ONE sentence that the team will contact them about their project, then stop. Do NOT ask for a phone number, more requirements, or anything further.
> * DISQUALIFIED EXIT — decline politely in one short message; do NOT show the contact form or collect any details. This applies even if the visitor's details were shared earlier. Under $2,000: our custom projects start at $2,000, so we won't be the right fit this time — our website templates and guides may be exactly what they need.
> * Job applications or agency partnerships → not a lead; point them to the contact page.
>
> **EXAMPLES**
>
> Visitor: "How much would a website for my bakery cost?"\
> Correct — You: "The team shares an exact estimate once they've scoped your project on a quick call. Roughly what budget did you have in mind?"
>
> Visitor: "My budget is around $800."\
> Incorrect — You: "We can probably make that work — let me take your details!" (Why wrong: breaks the $2,000 minimum and captures a lead the team can't serve.)\
> Correct — You: "Our custom projects start at $2,000, so we won't be the right fit this time — but our ready-made templates might be exactly what you need!"
And back its limits with these **Hard rules** under **Instructions → Agent rules**:
* We take on projects starting at $2,000. Below that, politely point the visitor to our templates and guides instead — never collect their details.
* Never estimate a price or a delivery date — both come from the team on the consultation call.
* Detailed scoping happens on the consultation call, not in chat. Once you understand roughly what the visitor needs, move forward.
You don't have to copy this exactly. But the shape is the lesson: the playbook carries the flow — goal, steps, gates, edge cases, exits — and the limits it depends on are enforced by Hard rules.
Keep each playbook to one job. Several short, focused playbooks work better than one long one that tries to cover everything.
***
## Why limits live outside the playbook
Notice what the example's playbook does and doesn't carry. The **flow** — gates, exits, edge cases — is in the playbook, because flow answers *where and when*: check the budget at step 4, end in exactly one exit. But the **limits themselves** — the $2,000 minimum, "never estimate a price" — are written as Hard rules.
Here's why. A limit stated only inside a playbook's text is followed most of the time — but under pressure ("can't you make an exception, just this once?"), it can bend. **Hard rules** don't bend: they're never broken, even if a playbook says otherwise, and they hold in *every* conversation — whether a playbook is active or not.
So the division of labor is: **the playbook references the limit in its flow; the Hard rule enforces it.** Any limit where bending costs you money or reputation — a minimum budget, a capacity range, a refund policy — gets a Hard rule.
***
## Best practices
**1. Start with the goal.** When your agent understands what success looks like, it can handle surprises and still find its way back. A playbook that's only a list of steps falls apart the moment a visitor deviates.
**2. Put checks inside the steps.** If an answer decides whether the conversation continues, check it *at the step where you ask for it* — not in a note at the bottom. Your agent follows steps in order and can skim past trailing notes.
**3. Tell it when to stop.** The most common playbook problem is an agent that doesn't know it's done. After the form is submitted, one thank-you sentence and stop — otherwise it keeps asking bonus questions ("And your phone number? Any other requirements?"). That's what the QUALIFIED EXIT in the example is for.
**4. Describe conditions by what's known, not by counting.** "Ask at most two questions" doesn't work — your agent can't count its own questions. "Once you know the service and a rough idea of the project, move to the form" works every time.
**5. Never ask your agent to do something it can't.** If it has no calendar, a step like "check availability" forces it to make an answer up. The honest pattern for any real-world action: collect the visitor's preference, and say the team confirms.
***
## How your agent uses them
Your agent reads the situation and loads the matching playbook **during** the conversation — you don't have to route anything yourself. If no playbook matches, it falls back to your [persona and rules](/documentation/chatbot-editor/instructions.md).
{% hint style="info" %}
Playbooks work best when your agent also has the **knowledge** to complete them. A playbook that asks which service the visitor wants needs your service list in [KNOWLEDGE](/documentation/chatbot-editor/step-2-training.md).
{% endhint %}
***
## Before you go live
Three quick checks — if any of these is off, your agent has to improvise, and that looks like a broken playbook:
* **The features your steps use are switched on.** If a step says "show the contact form", make sure lead capture is enabled under [ACTIONS](/documentation/chatbot-editor/step-4-actions.md) and collects the same fields your playbook expects.
* **Your Identity defers to the playbook.** Its Goal should include: *"The active playbook defines your steps and limits — follow it exactly."* And the Identity shouldn't mention collecting details — that's the playbook's job. See [Writing a good Identity](/documentation/chatbot-editor/instructions.md#writing-a-good-identity).
* **Your limits are backed by Hard rules** under Agent rules — the playbook references them, the Hard rules enforce them (see above).
***
## Test it like a real visitor
Use **Test agent** (top right) and role-play the situation yourself — starting a **fresh conversation for each test**, since an old thread remembers earlier mistakes.
* Play a cooperative visitor and go all the way to the finish.
* Try each decline case (under budget, work you don't offer) — these fail silently most often.
* Wander off mid-way ("do you have parking?") and see if the agent comes back to the flow.
* Decline the contact form.
* Push on a limit ("can't you make an exception?").
One habit makes your tests realistic: **answer only what the agent asks**, like a real visitor would. If you volunteer everything upfront, you'll never see the problems your visitors will.
{% hint style="info" %}
Two more habits: **turn a playbook off instead of deleting it** if you only need it seasonally, and **test after every change** — small wording edits can change behavior more than you'd expect.
{% endhint %}
***
## Related Topics
* [BEHAVIOR: Instructions](/documentation/chatbot-editor/instructions.md) — Persona and the rules that always apply
* [KNOWLEDGE](/documentation/chatbot-editor/step-2-training.md) — What your agent knows
* [ACTIONS](/documentation/chatbot-editor/step-4-actions.md) — Lead capture, handover, and buttons a playbook can lead into
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://aibotkit-docs.gitbook.io/documentation/chatbot-editor/playbooks.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.