> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unpod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# What is a playbook

> A playbook is a short, plain-language document that tells the agent who it is, what it must accomplish, and when a step is done. Checkpoints gate outcomes, not utterances - and a fast Talker plus an async Director run the whole thing.

## In one sentence

A **playbook** describes an outcome-driven conversation in plain language.
Instead of drawing a flow chart with every branch, or stuffing everything into
one prompt, you write **checkpoints** - the things that must be true before the
conversation moves on. It is the instruction set an
[Agent Workforce](https://docs.unpod.ai/agent-studio/agent-workforce.md) worker runs against - one
agent, one step, one conversation.

## Why not a big prompt or a graph

A big prompt fails by **confusion** - the longer it grows, the more the model
skips rules. A hand-drawn graph fails by **latency and rigidity** - extra model
calls per node, and real callers walk off your edges.

| | Big prompt | Rigid graph | **Playbook** |
| - | - | - | - |
| **Steering** | One long prompt | Every edge hand-drawn | Checkpoints - declare the outcome |
| **Off-script caller** | Drifts | Hits an unhandled state | Engine finds the path |
| **Latency** | One call per turn | Extra calls per node | Talker streams, Director judges async |
| **Changing it** | Rewrite the wall of text | Rewire the graph | Add or edit a checkpoint |

The full model - and when a graph still earns its place - is in
[Thinking in playbooks](https://docs.unpod.ai/superdialog/thinking-in-playbooks.md).

## Checkpoints gate outcomes, not utterances

The engine decides what to *say* each turn. The checkpoints decide when the
conversation is allowed to *move on*. You describe the destination; you do not
script every sentence.

```yaml Example checkpoint theme={null}
- id: confirm_appointment
  purpose: Confirm the caller's Friday 4pm appointment.
  say: Offer Friday 4pm first, fall back to 5pm.
  done_when: The caller has said yes to a time, or asked to reschedule.
```

That is the whole mental model: **checkpoints gate outcomes, not utterances.**

## The parts of a playbook

| Part | What it is |
| - | - |
| **Persona** | Who the agent is and how it sounds - the voice and tone a caller hears. |
| **Opening** | The first line the agent says when the conversation starts. |
| **Steps (checkpoints)** | The ordered outcomes that must be met. Each has a `purpose` and a `done_when`. |
| **`done_when` / `advance_when`** | The plain-language condition that lets the conversation leave a checkpoint. |
| **Slots** | The pieces of data to capture along the way (order number, callback, a chosen time). |
| **Interrupts** | Conditions that can fire from any step - "goodbye", "I'm busy" - to end or redirect gracefully. |

Field-by-field reference for both authoring formats is in
[Playbooks](https://docs.unpod.ai/superdialog/playbooks.md).

```yaml A small, complete playbook theme={null}
goal: Confirm the caller's appointment for Dr. Lee's clinic.
persona:
  name: Mira
  identity: A warm, efficient scheduling assistant for Dr. Lee's clinic.
  voice_style: Calm, brisk, never pushy.
opening: "Hi, this is Dr. Lee's office calling to confirm your appointment."
playbook:
  - id: confirm_time
    purpose: Confirm the Friday 4pm slot, or offer 5pm.
    say: Offer Friday 4pm first, fall back to 5pm.
    done_when: The caller accepts a time or asks to reschedule.
  - id: wrap_up
    purpose: Read back the confirmed time and say goodbye.
    done_when: The caller has heard the confirmed time.
    terminal: true
    outcome: confirmed
```

## How it runs: Talker + Director

A playbook is fast because two roles run at once:

> [card] Talker
>
> Streams every spoken reply the moment it can, so the caller hears a natural,
> immediate response - no waiting on bookkeeping.

> [card] Director
>
> Runs **asynchronously**: reads the transcript, extracts slot data, judges
> whether a checkpoint's `done_when` is met, and runs any tools - over an
> event-sourced log.

Turn ordering, the event-sourced log, and why the Director never blocks the
Talker are covered in [Architecture](https://docs.unpod.ai/superdialog/architecture.md).

> [card] [The full checkpoint model](https://docs.unpod.ai/superdialog/thinking-in-playbooks.md)
>
> Go deeper on `done_when` / `advance_when`, slots, and interrupts in the
> mental-model guide.

## Where playbooks come from

You rarely hand-write the YAML from scratch. You author a playbook by **talking
to a builder agent in the Playground** - describe the job, and it writes the
checkpoints for you.

> [card] [What is the Playground](https://docs.unpod.ai/agent-studio/playground.md)
>
> The browser app where you author, test, optimize, and ship a playbook.

> [card] [Build an agent playbook](https://docs.unpod.ai/agent-studio/build-an-agent.md)
>
> The hands-on walkthrough: describe an agent and watch its playbook appear.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.