Chat Agent

Minimal durable AI chat agent using a SQLite-backed Durable Object. Workers AI is optional - without an AI binding the agent echoes agent: <message>.

FeaturesCopy Anchor Link

• Per-session chat history in Durable Object SQLite
• POST /chat for request/response turns
• GET /chat for history
• WebSocket upgrade on GET /ws for realtime updates
• Optional Workers AI replies when the AI binding is available

API ReferenceCopy Anchor Link

POST /chatCopy Anchor Link

Send a user message and receive the updated message list (including the assistant reply).

sessionId string (required)

Session id (letters, numbers, _, -).

message string (required)

User message (max 4,000 characters).

Example RequestCopy Anchor Link

curl -X POST "https://your-worker.workers.dev/chat" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"demo","message":"Hello"}'

Success ResponseCopy Anchor Link

{
  "sessionId": "demo",
  "messages": [
    { "role": "user", "content": "Hello" },
    { "role": "assistant", "content": "agent: Hello" }
  ]
}

GET /chatCopy Anchor Link

Return chat history for a session.

sessionId string (required)

Example RequestCopy Anchor Link

curl "https://your-worker.workers.dev/chat?sessionId=demo"

GET /wsCopy Anchor Link

WebSocket upgrade for realtime message updates. Send { "message": "..." } over the socket; receive { "type": "messages", "messages": [...] }.

sessionId string (required)

Requires Upgrade: websocket.

Error CodesCopy Anchor Link

• 400 - Invalid session, message, body, or missing WebSocket upgrade (INVALID_SESSION, INVALID_MESSAGE, INVALID_BODY, EXPECTED_WEBSOCKET)
• 502 - Chat or Durable Object failure (CHAT_ERROR)

Use CasesCopy Anchor Link

• Learn Agents / Durable Object chat session patterns
• Prototype multi-turn AI assistants with persistent history
• Add WebSocket streaming alongside HTTP chat APIs
• Compare stub echo replies vs Workers AI generation

LimitationsCopy Anchor Link

• Without Workers AI, replies use the stub format agent: <message>
• Message max 4,000 characters; no auth on sessions
• Demo is single-agent per session id, not multi-user rooms
• WebSocket clients must send JSON { "message": "..." }

DeploymentCopy Anchor Link

curl -X POST "https://your-worker.workers.dev/chat" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"demo","message":"Hello"}'

Local DevelopmentCopy Anchor Link

cd apps/experiments/chat-agent
npm install
npm run dev

curl -X POST "http://localhost:8787/chat" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"demo","message":"Hello"}'

AI replies require a Workers AI binding. Without it, replies use the stub format.

ConfigurationCopy Anchor Link

wrangler.json declares:

• Durable Object binding CHAT_AGENT → ChatAgent
• Migration v1 with new_sqlite_classes: ["ChatAgent"]
• Workers AI binding AI

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• Durable Objects - SQLite-backed chat sessions
• Workers AI - Optional model replies
• WebSockets - Realtime /ws upgrades