Thinking in Playbooks
If you have built LLM chatbots before, SuperDialog’s default engine asks for one shift in thinking:
The key move: checkpoints gate outcomes, not utterances. You don’t script
what the agent says next - you declare what “done” means for each step, and the
model speaks freely to get there.
The core model
A playbook is one or more journeys, each a list of checkpoints. A checkpoint is a call-center-script unit with four parts:goal- what “done” means for this step (“Have the city, date, and party size”)slots- typed data to extract while here (city: str,date: date,players: int)guidance- prose the agent speaks from (it owns the wording)advance_when- an ordered list of rules that move the conversation forward
purpose / collect / say / done_when; both compile to one checkpoint - see
Playbooks.
Playbook checkpoint model
Checkpoint · collect_details
goalCity + date + party size
slots
city · date · playersguidanceCollect naturally
advance_whenDetails complete, or course info
Free conversationThe model talks; any order, one breath, changed minds
outcome met
Next
Next checkpointThe framework owns progress
SuperDialog runs itYou write it
Start with the topology, then write the steps
Before writing any prose, map your conversation:- What are the distinct steps (checkpoints) in this conversation?
- What data (slots) must each step capture?
- What outcomes move the conversation forward (advance rules)?
- What can go wrong at each step? (caller refuses, asks a side question)
superdialog generate produces:
Test it - no infrastructure needed
salon.yaml, re-run chat - the loop
takes seconds.
Soft gates vs hard gates
Every checkpoint has agate. This is where fluidity meets reliability:
- Soft gate (default) - provisional values are enough; the agent never blocks. The model keeps the conversation moving and the extracted data settles in the background. Use it for everything that isn’t irreversible.
- Hard gate - for payments, identity, anything you can’t undo. Required slots must be confirmed (not just provisionally extracted), and the agent briefly waits for that confirmation before it speaks the gated line. A single model guess can never push past a hard gate on its own.
Why one streaming call, not two
A rigid graph has to make two LLM calls per turn: one to decide which edge fires, then one to speak. For voice, that adds latency before the caller hears anything. A playbook splits the turn instead: a fast Talker streams the spoken reply in one LLM call, while an async Director extracts slots and judges advance rules off the speech path. The caller hears the agent immediately; correctness converges a beat behind. Full runtime - ordering, the event log, barge-in safety - in Architecture.When a graph still fits
The checkpoint model is the default and the right choice for most conversations. A hand-authored flow graph still earns its place when:- Compliance / auditability - you need every reachable path enumerable and lintable as a spec.
- Strict determinism - the conversation truly is a fixed decision tree with no room for the model to improvise.
Playbook.load detects flow JSON and converts it), and
you can still run the original graph runtime with engine="flow" /
superdialog chat --mode flow. See Flows for graph
authoring and the migration path.
Next steps
Playbooks
The simple and full authoring formats
Quickstart
Generate and run your first playbook
Architecture
The Talker/Director runtime and event log
Flows (legacy)
Graph authoring and the migration path