Skip to main content

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.
Animated SuperDialog text loop diagram showing user text entering the Agent protocol, agent.turn using tools and state, and reply text coming back.
It ships two engines behind one 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.
It is intentionally narrow in scope. Audio, STT, TTS, telephony, and media servers are all out of scope - those belong to voice infrastructure like LiveKit, PipeCat, or the Unpod Voice Platform. SuperDialog ends at text in, text out - on both engines.

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

AudienceWhy they care
Voice developer using LiveKit / PipeCatDrop 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 flowsAuthor 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 LLMPlug any LLM URI and get the full framework for free
Unpod Voice Platform customerSuperDialog 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.
from superdialog import DialogMachine

agent = DialogMachine("booking.yaml", llm="openai/gpt-4.1-mini")
result = await agent.turn("hello")
DialogMachine (legacy, opt-in)Playbook (default)
Authoring unitGraph node + edgesCheckpoint (goal, slots, guidance, advance rules)
Who owns fluidityThe graphThe model, inside checkpoints
What is gatedEvery transitionOutcomes (slots + advance rules; hard gates where irreversible)
LLM calls on speech pathTwo serial (route, then speak)One streaming call; Director runs async
StreamingChunked after the factReal token streaming, barge-in safe
StateSnapshot contextEvent-sourced log (replay, audit, eval)
Best forDeterministic compliance flowsConversations that must feel human
Why the engines swapped places, honestly: users don’t follow graphs. The graph-railed model accumulated stacked escape hatches and still cost two serial LLM calls per turn with only cosmetic streaming. The Playbook engine moves fluidity to the model and keeps the framework’s authority where it belongs: on outcomes. Existing flows are migrated, not replaced - 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)

CapabilityStatus
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