When to use this
- Text-only chatbot (no voice)
- Support widget (Intercom, Zendesk, custom)
- WhatsApp or SMS webhook
- Any HTTP-based channel
Single-user (stateless)
For simple cases where one machine handles one conversation at a time:Multi-user (SessionWorker)
For multi-user or multi-worker deployments, route each conversation through aSessionWorker:
SessionWorker:
- Creates one agent per active session
- Shares the immutable playbook by reference
- Serialises concurrent requests for the same
session_id - Runs concurrent requests for different session IDs fully in parallel
result.metadata carries checkpoint, version, ended, and (on terminal
checkpoints) outcome.
Streaming endpoint
On the Playbook engine the stream is live provider tokens from the Talker - not post-hoc chunking:Using FastAPIRouter
The built-in adapter mounts/turn, /stream, and /reset in one line:
Request / response shape
Deploying to production
For production multi-worker FastAPI:- Replace
InMemorySessionStorewith a distributedSessionStore(RedisSessionStoreis planned; implement theSessionStoreprotocol today) so state survives across workers - Set
max_sessionsonSessionWorkerto cap memory usage - Use
NullSessionStoreif your sessions are fully stateless (e.g. webhook-per-message pattern)
The in-process
SessionWorker works as-is because agents stay cache-resident,
but durable or multi-worker resume on the Playbook engine requires persisting
agent.event_log.to_jsonl() yourself and restoring via load_event_log -
SessionWorker’s SessionRecord persists chat_ctx / flow_state only, which
loses playbook state fidelity. External events (webhooks, timers, silence) go to
agent.runtime.on_external(...) from your own endpoints.