Skip to main content
session_workspace Sessions let you build agents that remember context within a conversation.

The Problem

Without sessions, each request might hit a different worker:
  • Request 1 → Worker A (loads user context)
  • Request 2 → Worker B (no context, starts fresh)
With sessions, same user always hits same worker:
  • Request 1 → Worker A (loads user context)
  • Request 2 → Worker A (context already loaded)

Enable Sessions

Add a session ID to your requests: CLI:
HTTP:

Example: Conversational Agent

Test Session Affinity

Session + Workspace

For durable state (survives worker restarts), combine sessions with workspace:

How It Works

  1. Request arrives with session_id
  2. Orpheus checks if a worker handled this session before
  3. If yes → route to that worker
  4. If no → pick any available worker, remember the mapping

Limitations

  • Best-effort: If preferred worker is busy, request goes to another
  • Worker death: If worker dies, next request gets new worker
  • Single machine: Session mappings are local (not distributed)

When to Use Sessions

Next: Workspace Persistence

Make state survive worker restarts →