> ## 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.

# Why playbooks

> Every agent needs a way to steer the LLM. The two common approaches - one giant prompt, or a hand-drawn state graph - each break at scale, in opposite ways. Playbooks were built to keep the good half of each and drop the pain.

## The problem we set out to solve

Building a voice or chat agent is mostly one decision: **how do you steer the
model, turn after turn, so it reliably reaches an outcome?** A demo works with
any approach. Production - hundreds of real callers who interrupt, change their
mind, and go off-script - is where the approach you picked either holds or
falls apart.

Teams reach for one of two patterns today. Both work at first. Both break as the
agent grows - in **opposite** directions.

## The two common approaches (and where each breaks)

<CardGroup cols={2}>
  <Card title="Prompt-based agent" icon="scroll-text">
    One giant system prompt holds the persona, every rule, every edge case, and a
    pile of examples. Simple to start.
  </Card>

  <Card title="Graph / node-based agent" icon="workflow">
    A state machine: every state is a node, every transition an edge you author
    by hand, with explicit criteria. Precise to start.
  </Card>
</CardGroup>

### 1. Prompt-based agents drown in their own prompt

You put everything into the prompt and let the model sort it out. It reads well
on day one. Then the prompt grows:

* **More instructions compete for attention.** As the prompt gets longer, the
  model loses focus - it skips steps, forgets a rule you added, and contradicts
  earlier lines. **More prompt buys more confusion, not more control.**
* **No structure to test.** When it misbehaves you cannot point at *which* line
  caused it. Every fix is a reshuffle of one wall of text, and every edit risks
  a regression somewhere else.
* **No notion of "progress."** The prompt has no idea whether the conversation
  has actually accomplished anything - it just keeps talking.

<Warning>
  The prompt-based failure mode is **confusion**: a bloated prompt makes the agent
  less reliable the more you ask of it.
</Warning>

### 2. Graph / node-based agents are rigid and slow

So you go the other way and draw the whole conversation as a graph - nodes,
edges, criteria for each transition. Now everything is explicit. But:

* **Latency piles up.** Every turn has to walk the graph and often makes extra
  model calls per node to decide the next edge. Those round-trips stack into
  audible lag on a live call.
* **Real callers go off-script.** People do not follow your edges. The moment a
  caller does something you did not draw, they hit an unhandled state.
* **Authoring and upkeep are brittle.** Enumerating every branch is slow, and
  each new requirement means rewiring the graph. It does not bend; it breaks.

<Warning>
  The graph-based failure mode is **latency and rigidity**: precise, but slow to
  run and painful to change.
</Warning>

## Enter the playbook

A **playbook** was built to keep the good half of each approach and drop the bad
half of both. It reads like a prompt, holds its shape like a graph, and runs
fast:

<CardGroup cols={2}>
  <Card title="Plain language, but structured" icon="book-open">
    You write in plain English like a prompt - but it is organized into
    **checkpoints**, so the model is never handed one giant wall of text to get
    lost in.
  </Card>

  <Card title="Outcome-gated, but not hand-drawn" icon="target">
    Like a graph it tracks progress toward a goal - but you **declare what "done"
    means**, not every edge. The engine finds the path, so off-script callers do
    not fall off a cliff.
  </Card>

  <Card title="Fast by design" icon="zap">
    A **Talker** streams the spoken reply immediately while a **Director** judges
    progress and runs tools **asynchronously** - no per-node round-trip tax, so
    the call stays snappy.
  </Card>

  <Card title="Testable and eval-able" icon="flask-conical">
    Because progress is expressed as checkpoints, you can score whether each one
    was met, find the weak one, and fix it in isolation.
  </Card>
</CardGroup>

### Side by side

|                        | Prompt-based                  | Graph / node-based    | **Playbook**                              |
| ---------------------- | ----------------------------- | --------------------- | ----------------------------------------- |
| **Steering**           | One long prompt               | Every edge hand-drawn | Checkpoints (declare the outcome)         |
| **Main failure**       | Confusion as it grows         | Latency + rigidity    | —                                         |
| **Off-script callers** | Drifts                        | Hits unhandled states | Engine finds the path                     |
| **Latency**            | One call/turn, but unreliable | Extra calls per node  | Talker streams now, Director judges async |
| **Authoring**          | Rewrite the wall of text      | Rewire the graph      | Add or edit a checkpoint                  |
| **Testable**           | Hard - no structure           | Per-edge, brittle     | Per-checkpoint scoring                    |

<Note>
  This is exactly the split inside [SuperDialog](/superdialog/introduction): the
  **Playbook engine** (default) is the checkpoint model above; the older
  graph-railed **DialogMachine** is still supported and now runs *compiled on the
  Playbook engine*, so existing graphs keep working while new work goes to
  playbooks.
</Note>

## Next

<Card title="What a playbook actually is" icon="book" href="/playbook/what-is-a-playbook">
  Now that you know *why*, see the checkpoint model itself - persona, `done_when`,
  slots, and the Talker/Director loop - with a real example.
</Card>