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 (a sessionId is generated for you on the first message)
  • 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

Custom Routers

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

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 and will be key for future protocol and permission use cases

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! 🚀