Build a stateful AI agent on Durable Objects with the Cloudflare agents SDK, using persisted state, embedded SQL, and scheduled tasks

Documented steps

1. Install the SDK: `npm i agents` in a Wrangler-based Workers project.
2. Define the agent: `export class MyAgent extends Agent<Env, State> { ... }`. Each instance is backed by its own Durable Object with embedded SQLite.
3. Implement the lifecycle hooks you need: `onStart(props?)`, `onRequest(request)` for HTTP, `onConnect(connection, ctx)` / `onMessage(connection, message)` / `onClose(connection, code, reason, wasClean)` / `onError(connection, error)` for WebSockets, and `onEmail(email)`.
4. Manage state with `this.setState(newState)` — it persists to the instance's SQLite storage AND broadcasts to every connected client. React with `onStateChanged(state, source)` where source is "server" or the client Connection that made the change.
5. Guard against feedback loops inside onStateChanged with `if (source === "server") return;` before reacting to a change you yourself made.
6. Use embedded SQL via tagged templates: `this.sql\`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)\`` and `this.sql<User>\`SELECT * FROM users WHERE id = ${userId}\``. Keep small UI-facing data in state and larger historical data in SQL.
7. Schedule work with `await this.schedule(when, callbackMethodName, payload)` where `when` is a delay in seconds, a Date, or a cron string: `await this.schedule(60, "sendReminder", { message: "Check email" })` or `await this.schedule("0 8 * * *", "dailyDigest", { userId: "123" })`.
8. Manage schedules with `await this.getScheduleById(id)`, `await this.listSchedules({ type: "cron" })`, and `await this.cancelSchedule(id)`. Prefer the async `listSchedules()` over the deprecated synchronous `getSchedules()`.
9. Call models from inside the agent: Workers AI needs no API key — `await this.env.AI.run("@cf/deepseek-ai/deepseek-r1-distill-qwen-32b", { prompt, stream: true })`. Or use the Vercel AI SDK with `createWorkersAI({ binding: this.env.AI })`, or any OpenAI-compatible client with the key in `this.env.<SECRET>`.
10. Route requests to instances from the Worker's default fetch handler: `const res = await routeAgentRequest(request, env); if (res) return res;`. This maps `/agents/:agent-name/:instance-name` URLs to the right Durable Object.
11. Configure the binding in wrangler.jsonc: `"durable_objects": { "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }] }` — `name` is the env property used in code and `class_name` must match the exported class exactly.
12. Provision SQLite storage with the modern exports field: `"exports": { "MyAgent": { "type": "durable-object", "storage": "sqlite" } }`. Existing Workers using the legacy `migrations` array with `new_sqlite_classes` continue to work, but exports is preferred for new projects.
13. Generate typed bindings: `npx wrangler types env.d.ts --include-runtime false`, producing an Env interface with the AgentNamespace binding.
14. Sync state on the client with `useAgent({ agent: "game-agent", name: "room-123", onStateUpdate: (state, source) => {...} })` in React, or `new AgentClient({ agent, name, onStateUpdate })` in vanilla JS; call `setState({...})` to push updates back.
15. To host a remote MCP server instead of a custom agent API, extend `McpAgent` from `agents/mcp`, set `server = new McpServer({ name, version })`, register tools in `async init()` via `this.server.tool(name, zodSchema, handler)`, and export `export default MyMCP.serve("/mcp")` for Streamable HTTP.
16. Official documentation (verify before relying on limits, which change): https://developers.cloudflare.com/agents/ | https://developers.cloudflare.com/agents/api-reference/agents-api/ | https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/ | https://developers.cloudflare.com/agents/api-reference/schedule-tasks/ | https://developers.cloudflare.com/agents/api-reference/configuration/ | https://developers.cloudflare.com/agents/api-reference/using-ai-models/ | https://developers.cloudflare.com/agents/model-context-protocol/mcp-agent-api/ | https://developers.cloudflare.com/agents/model-context-protocol/transport/