Overview
SuperDialog is the brain layer for conversational systems - it works anywhere, and shines on Unpod. It takes a prompt or an authored artifact and turns it into a running conversation runtime - managing turn-by-turn logic, tool calls, outcome tracking, and conversation memory.
Agent protocol, and the Playbook
engine is the default everywhere:
- Playbook engine (default) - checkpoints gate outcomes, not utterances. A fast Talker streams every spoken turn while an async Director extracts data, judges progress, and runs tools over an event-sourced log. This is where new investment goes.
- DialogMachine (supported legacy) - the graph-railed state machine: nodes,
edges, and criteria, where every transition is authored. Still fully
supported, opt-in via
engine="flow". Existing flow graphs run compiled on the Playbook engine by default, so nothing breaks.
New to the checkpoint model?
Read the mental-model guide before diving into the quickstart.
SuperDialog on GitHub
Browse the source, issues, and releases at
unpod-ai/superdialog.Coming from the Speech Stack? Assign your SuperDialog agent to
ctx.session.dialog_machine and the SDK wraps it for you - see
Level Up to SuperDialog.Why SuperDialog exists
The brain has natural reuse beyond voice
A conversation brain that runs a customer-onboarding journey works the same whether the user is on a phone, a WhatsApp thread, an Intercom widget, or a CLI test harness. Coupling it to telephony forecloses every non-voice use case.The dependency direction matters
Voice infrastructure should depend on SuperDialog (as one brain option), not the other way around. A modular architecture keeps the framework portable and the platform composable.Who it’s for
| Audience | Why they care |
|---|---|
| Voice developer using LiveKit / PipeCat | Drop SuperDialog in as the brain; PlaybookAgent gives real token streaming through the same adapters |
| Chatbot developer (text-only) | superdialog generate a playbook, chat against it from the CLI, embed it with FastAPI through the Agent protocol |
| Developer with compliance / scripted flows | Author the flow graph as the spec - every path enumerable and lintable - and run it compiled on the Playbook engine, or on DialogMachine via --mode flow |
| Enterprise dev with a custom LLM | Plug any LLM URI and get the full framework for free |
| Unpod Voice Platform customer | SuperDialog is the default brain Unpod offers - same code runs locally and in Unpod cloud |
How it compares
SuperDialog is to conversation flow what n8n is to integration workflow - a simple, composable, eval-able runtime for orchestrating turn-by-turn logic. Where LangChain and LangGraph expose general agent primitives, SuperDialog focuses narrowly on the conversational core: who speaks next, what to say while tools run, which checkpoint or flow the conversation is in, when to call a tool, when to escalate, and which outcome the session ended with. The pitch: “if your problem is conversation state, this is the right size.”Two engines, one entry point
DialogMachine is the recommended way in. It runs the Playbook engine by
default; pass engine="flow" for the legacy graph runtime. Both engines sit
behind the same Agent protocol, so sessions and host adapters run either one
unchanged.
| DialogMachine (legacy, opt-in) | Playbook (default) | |
|---|---|---|
| Authoring unit | Graph node + edges | Checkpoint (goal, slots, guidance, advance rules) |
| Who owns fluidity | The graph | The model, inside checkpoints |
| What is gated | Every transition | Outcomes (slots + advance rules; hard gates where irreversible) |
| LLM calls on speech path | Two serial (route, then speak) | One streaming call; Director runs async |
| Streaming | Chunked after the fact | Real token streaming, barge-in safe |
| State | Snapshot context | Event-sourced log (replay, audit, eval) |
| Best for | Deterministic compliance flows | Conversations that must feel human |
Playbook.load
detects flow JSON and compiles it (compile_flow), with coverage_report
proving every node, edge, and action mapped.
What ships today (v0.2)
| Capability | Status |
|---|---|
| Playbook engine: checkpoints, Talker/Director compound, event-sourced log | ✅ shipped |
Real token streaming, barge-in safe (PlaybookAgent) | ✅ shipped |
Prompt → playbook: superdialog generate / generate_simple_playbook (default creation path) | ✅ shipped |
DialogMachine(source, llm) - one entry point, Playbook by default | ✅ shipped |
| Sandboxed declarative tools and Director pipelines (HTTP + python, retry/middleware) | ✅ shipped |
Flow → playbook migration: compile_flow, coverage_report | ✅ shipped |
Replay + persona eval bridge: replay, run_session, run_eval | ✅ shipped |
superdialog eval CLI (flow audit / synthetic corpus) | ✅ shipped |
superdialog optimize (playbook run → eval → improve loop) | ✅ shipped |
Prompt → flow graph (legacy): create_dialog_flow | ✅ v0.1 |
| Tools: Python callables, HTTP endpoints, MCP servers | ✅ v0.1 |
Multi-flow (legacy): FlowSet + switch_flow | ✅ v0.1 |
| Adapters: LiveKit, PipeCat, FastAPI, WebSocket | ✅ v0.1 |
SessionWorker - multi-conversation lifecycle + persistence | ✅ v0.2 |
LLMAgent, LangChainAgent - non-DM brains in SessionWorker | ✅ v0.2 |
| Distributed stores (Redis, File, SQLite) + RedisLockBackend | 🔜 planned |
| Voice-event plumbing (silence / barge-in fed into the event log) | 🔜 planned |
What it explicitly is not
- Not a UI flow designer - that belongs to a downstream tool
- Not a voice framework - audio, STT, TTS are out of scope (the Talker streams text tokens; the host turns them into speech)
- Not multi-modal - text only at the interface (vision/audio via tools if needed)
- Not a hosted service - SuperDialog is a library; the Unpod Voice Platform provides hosting for those who want it