Sessions


Sessions

Sessions enable you to maintain conversation context across multiple interactions. Every agent conversation gets its own unique session powered by Cloudflare Durable Objects, giving you persistent, stateful conversations that scale automatically.

The Magic: Durable Objects

The key insight is that each session maps to a unique Durable Object instance. When you route to /agent/chat/abc123, you're talking to the same persistent object every time. This is where the magic happens - your conversation state, memory, and context live in that specific instance.

typescript

Quick Start: Default Router

The simplest setup uses our default Hono router. It automatically handles session IDs and routes to the right agent instance:

typescript

That's it! You now have:

  • POST /agent/chat/:sessionId - Send messages to a specific session
  • Automatic Durable Object routing
  • Persistent conversation state

How Session Routing Works

The router implementation (source) follows this pattern:

  1. Extract session ID from the URL path (/agent/chat/abc123)
  2. Generate Durable Object ID from the session ID
  3. Route to specific agent instance using AGENT.get(id)
  4. Maintain conversation state in that persistent object
typescript

Session ID Patterns

UUID Sessions (Default)

bash

User-Based Sessions

bash

Custom Session Naming

bash

The session ID becomes the Durable Object name, so make it meaningful!

Custom Routers

You don't need the default router. Here's a minimal custom implementation (example):

typescript

JWT-Based User Sessions (Coming Soon)

Here's how you might implement user-specific sessions with JWT tokens:

typescript

The Agent Implementation

Your actual agent (source) runs inside the Durable Object:

typescript

Key Points

✅ Do This

  • Always route to AGENT.get(id) - This is crucial for persistence
  • Use meaningful session IDs - They become Durable Object names
  • Let the framework handle state - It's built for this

❌ Avoid This

  • Don't try to manage state outside the agent
  • Don't create new Durable Object IDs for the same session
  • Don't skip the routing layer - it handles the magic

Production Patterns

Health Checks

typescript

Session Management API

typescript

Session Cleanup

typescript

Next Steps

Remember: The session is just a routing mechanism. The real magic happens inside your Durable Object agent instance. Keep it simple, let the framework handle the complexity, and focus on building great conversational experiences! 🚀

Contact Us

Tell us a little about your project and how to reach you.