CLI Chatbot

Why start here

Before setting up any voice infrastructure, test your agent in a terminal. You get the full end-to-end dialog experience - same logic, same LLM calls, same tool execution - with nothing but Python. This is also the recommended build loop:

superdialog generate a playbook from a prompt
Chat with it in the CLI
Iterate on the prose, slots, and advance rules
Only then wire it into LiveKit / PipeCat / Unpod

Option 1: bundled CLI

superdialog generate "Confirm KYC. Ask for Aadhaar last 4. Confirm DOB." \
  --output kyc.yaml
superdialog chat kyc.yaml

The CLI reads OPENAI_API_KEY / ANTHROPIC_API_KEY from your environment and runs the playbook on the Playbook engine. chat defaults to ./playbook.yaml, then ./flow.json, and auto-detects any format. Override the model:

superdialog chat kyc.yaml --llm anthropic/claude-haiku-4-5

The per-turn status line ([checkpoint=<id> ended=<bool>]) names the live checkpoint so you can watch outcomes advance.

Option 2: Python REPL loop

For more control - custom tools, a split Talker/Director, or to inspect the event log:

import asyncio
from superdialog import DialogMachine

agent = DialogMachine("kyc.yaml", llm="anthropic/claude-haiku-4-5")  # any format

async def main():
    while True:
        user = input("> ")
        if user.strip() in ("quit", "exit"):
            break
        reply = await agent.turn(user)
        print(reply.text)

asyncio.run(main())

Inspect the event log. Drop to PlaybookAgent and agent.event_log.to_jsonl() is the audit artifact - every utterance, slot write, advance, and tool call, replayable offline:

from superdialog.playbook import Playbook, PlaybookAgent, httpx_http

agent = PlaybookAgent(
    playbook=Playbook.load("kyc.yaml"),
    talker_llm=talker, director_llm=director, http=httpx_http,
)

Legacy graph engine. superdialog chat kyc.json --mode flow runs the original graph engine. In code, construct DialogMachine(Flow.load("kyc.json"), llm=..., engine="flow", traversal_dir="./traversal_history") and drive the same loop; traversal_dir writes a timestamped JSON per completed session (full node path, every turn, collected slots).

Which engine am I on?

The status line tells you: [checkpoint=<id> ended=<bool>] is the Playbook engine (the default); [<ms>ms] is the legacy DialogMachine (--mode flow). A bare --flow x.json shows the checkpoint form because flow JSON is compiled onto the Playbook engine.

When to move to the next step

Once your agent behaves correctly in the CLI:

Wire it into LiveKit for voice
Or add a FastAPI endpoint for a text chatbot
Or connect to Unpod Voice Infra for full telephony

Getting Started

Core Concepts

Reference

Embedding Guides

Why start here

Option 1: bundled CLI

Option 2: Python REPL loop

Which engine am I on?

When to move to the next step

​Why start here

​Option 1: bundled CLI

​Option 2: Python REPL loop

​Which engine am I on?

​When to move to the next step

Why start here

Option 1: bundled CLI

Option 2: Python REPL loop

Which engine am I on?

When to move to the next step