Skip to main content

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 a SessionWorker:
The 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:
  1. Replace InMemorySessionStore with a distributed SessionStore (RedisSessionStore is planned; implement the SessionStore protocol today) so state survives across workers
  2. Set max_sessions on SessionWorker to cap memory usage
  3. Use NullSessionStore if 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.