Sessions

When do you need sessions?

Sessions add a lifecycle and persistence layer on top of any Agent-protocol brain - the default PlaybookAgent and the legacy DialogMachine alike. A bare agent holds its conversation state in memory for the lifetime of the instance. This works perfectly for:

Voice calls (one machine per call, ephemeral)
CLI testing (single conversation, short-lived)
Simple single-user demos

You need SessionWorker when:

Multi-user: multiple concurrent conversations hit the same process
Multi-worker: requests are load-balanced across FastAPI workers or pods
Long-lived chat: conversations span hours or days and must survive restarts

The Agent Protocol

SessionWorker works with any brain that implements this Protocol:

class Agent(Protocol):
    async def turn(text: str, *, stream: bool = False) -> TurnResult | AsyncIterator[StreamChunk]
    def assist(text: str) -> None
    @property
    def chat_ctx(self) -> ChatContext
    def load_chat_ctx(ctx: ChatContext) -> None

The Playbook engine’s PlaybookAgent, the legacy DialogMachine, LLMAgent, and LangChainAgent all implement this.

SessionWorker

The agent_factory returns a fresh agent per session. Point DialogMachine at a playbook and you get the default engine; the factory is identical whatever the artifact:

from superdialog import DialogMachine, SessionWorker, InMemorySessionStore

worker = SessionWorker(
    agent_factory=lambda: DialogMachine("kyc.yaml", llm="openai/gpt-4.1-mini"),
    store=InMemorySessionStore(),
    max_sessions=1000,               # optional cap
)

Use it with an async context manager:

async with worker.acquire("user-42") as h:
    result = await h.turn("Hello")
    h.assist("The customer is a VIP - be especially warm.")
    print(result.text)

What acquire does:

Loads or creates the session for session_id
Acquires a per-session lock (serialises concurrent requests for the same id)
Yields a SessionHandle
On exit: persists state to the store and releases the lock

Requests for different session_ids run fully in parallel.

FastAPI multi-user example

from contextlib import asynccontextmanager
from fastapi import FastAPI
from superdialog import DialogMachine, SessionWorker, InMemorySessionStore

worker: SessionWorker

@asynccontextmanager
async def lifespan(app: FastAPI):
    global worker
    worker = SessionWorker(
        agent_factory=lambda: DialogMachine("kyc.yaml", llm="openai/gpt-4.1-mini"),
        store=InMemorySessionStore(),
    )
    yield

app = FastAPI(lifespan=lifespan)

@app.post("/turn")
async def turn(payload: dict):
    async with worker.acquire(payload["session_id"]) as h:
        result = await h.turn(payload["text"])
    return {"reply": result.text}

Session stores

Store	Status	Use case
`InMemorySessionStore`	✅ v0.2	Development, single-process
`NullSessionStore`	✅ v0.2	Voice (ephemeral, no persistence)
`RedisSessionStore`	🔜 v0.3	Multi-process, distributed
`FileSessionStore`	🔜 v0.3	Lightweight persistence
`SQLiteSessionStore`	🔜 v0.3	Local single-server

Switch stores by changing one line - the rest of the code stays the same:

# Development
store = InMemorySessionStore()

# Production (v0.3)
# store = RedisSessionStore(url="redis://localhost:6379")

Lock backends

Backend	Status	Use case
`AsyncioLockBackend`	✅ v0.2	Single-process (default)
`RedisLockBackend`	🔜 v0.3	Multi-process / distributed

Other agent brains

When you want sessions and persistence but no checkpoint or flow opinion at all - a raw chat brain:

from superdialog import LLMAgent, SessionWorker, InMemorySessionStore

# Raw chat brain - no flow, no slots
worker = SessionWorker(
    agent_factory=lambda: LLMAgent(
        llm="openai/gpt-5.1",
        system_prompt="You are a helpful customer support assistant.",
    ),
    store=InMemorySessionStore(),
)

Or with LangChain (requires pip install superdialog[langchain]):

from superdialog import LangChainAgent, SessionWorker, InMemorySessionStore

worker = SessionWorker(
    agent_factory=lambda: LangChainAgent(runnable=my_langchain_chain),
    store=InMemorySessionStore(),
)

Conversation state

Internally, each session stores a ChatContext - LiveKit-aligned message history:

@dataclass
class ChatMessage:
    role: Literal["system", "user", "assistant", "tool"]
    content: str

@dataclass
class ChatContext:
    items: list[ChatMessage]

Beyond the transcript, each engine carries its own runtime state:

Playbook engine - the source of truth is the event-sourced log (agent.event_log); ConversationState.fold(log, playbook) derives the checkpoint, slots, and outcome. Persist event_log.to_jsonl() and restore via load_event_log for full fidelity.
Legacy DialogMachine - FlowState (current node, slot values). Present only when the brain is a DialogMachine; None otherwise.

SessionWorker’s built-in SessionRecord persists chat_ctx / flow_state only. For durable or multi-worker resume on the Playbook engine, persist agent.event_log.to_jsonl() yourself and restore with load_event_log - otherwise playbook state fidelity (provisional vs confirmed slots, tool results) is lost.

Voice (ephemeral) pattern

For voice calls where each call is a fresh conversation and no persistence is needed:

worker = SessionWorker(
    agent_factory=lambda: DialogMachine("kyc.yaml", llm="anthropic/claude-haiku-4-5"),
    store=NullSessionStore(),   # writes are dropped; reads always return empty
)

NullSessionStore keeps the single-call lifecycle of a bare agent while still giving you the multiplexing and locking of SessionWorker.

Getting Started

Core Concepts

Reference

Embedding Guides

When do you need sessions?

The Agent Protocol

SessionWorker

FastAPI multi-user example

Session stores

Lock backends

Other agent brains

Conversation state

Voice (ephemeral) pattern

​When do you need sessions?

​The Agent Protocol

​SessionWorker

​FastAPI multi-user example

​Session stores

​Lock backends

​Other agent brains

​Conversation state

​Voice (ephemeral) pattern

When do you need sessions?

The Agent Protocol

SessionWorker

FastAPI multi-user example

Session stores

Lock backends

Other agent brains

Conversation state

Voice (ephemeral) pattern