What is a playbook

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.

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.

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.

Example checkpoint

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

A small, complete playbook

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:

Talker

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

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.

The full checkpoint model

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.

What is the Playground

The browser app where you author, test, optimize, and ship a playbook.

Build an agent playbook

The hands-on walkthrough: describe an agent and watch its playbook appear.

Agent Studio

SuperDialog Framework

Embed in your stack

What is a playbook

In one sentence

Why not a big prompt or a graph

Checkpoints gate outcomes, not utterances

The parts of a playbook

How it runs: Talker + Director

Talker

Director

The full checkpoint model

Where playbooks come from

What is the Playground

Build an agent playbook

​In one sentence

​Why not a big prompt or a graph

​Checkpoints gate outcomes, not utterances

​The parts of a playbook

​How it runs: Talker + Director

Talker

Director

The full checkpoint model

​Where playbooks come from

What is the Playground

Build an agent playbook

In one sentence

Why not a big prompt or a graph

Checkpoints gate outcomes, not utterances

The parts of a playbook

How it runs: Talker + Director

Where playbooks come from