Agents

Agents is Cloudflare’s SDK for building persistent, stateful execution environments for agentic workloads, built directly on top of Durable Objects. Instead of treating an agent as a stateless function call, each agent instance is a long-lived object with its own private storage, SQLite database, and lifecycle — it hibernates when idle and wakes on demand, so you can run millions of independent agents (one per user, per session, per game room) while paying nothing for inactive ones.

The framework provides the Agent base class along with request routing, WebSocket connection handling, scheduling (one-time, recurring, and cron), and a @callable() decorator for exposing type-safe RPC methods that a React frontend can call as if they were local functions, with state changes synced automatically to every connected client. Beyond the core primitives it bundles first-party building blocks for AI chat (message persistence, resumable streaming), MCP client/server support, durable multi-step workflows with human-in-the-loop approval, sandboxed code execution, and voice pipelines, making it a full toolkit for shipping agentic products on Cloudflare’s edge platform.

What You Get

• An Agent base class with persistent state, setState(), and automatic real-time sync of state changes to every connected client
• Type-safe RPC via the @callable() decorator, so client code can call server agent methods as if they were local functions
• Built-in WebSocket handling with lifecycle hooks, plus request routing (routeAgentRequest) for wiring agents into a Worker
• One-time, recurring, and cron-based task scheduling that survives Worker restarts
• First-party MCP support — agents can act as MCP servers or connect as MCP clients over HTTP, SSE, or RPC
• Durable multi-step workflows with human-in-the-loop approval, plus companion packages for AI chat, sandboxed code execution, and voice pipelines

Common Use Cases

• Per-user or per-session AI chat assistants that need durable conversation state and resumable streaming
• Multiplayer or collaborative apps (games, shared documents) where each room/session is its own stateful agent
• Long-running agentic workflows that call tools, wait on human approval, and must survive process restarts
• MCP servers and clients that need persistent connection state and OAuth-backed authentication

Under The Hood

Architecture - The core (packages/agents/src/index.ts) wraps Cloudflare’s partyserver Server class to build the Agent base class: incoming requests are routed via routeAgentRequest/routePartykitRequest to a named Durable Object instance, state mutations flow through setState() and are broadcast to connected Connection/WebSocket clients, and @callable()-decorated methods are exposed as RPC targets via cloudflare:workers’ RpcTarget. Scheduling (schedule.ts), MCP client/server support (src/mcp/), sub-agent routing (sub-routing.ts), and workflow tracking (workflow-types.ts) are layered on top of this same Durable Object primitive, with companion packages (@cloudflare/ai-chat, @cloudflare/think, @cloudflare/codemode, @cloudflare/shell, @cloudflare/voice) building higher-level features on the same base class.

Tech Stack - Pure TypeScript (98.8% of the repo) built with esbuild/Rolldown, targeting the Cloudflare Workers runtime. Core dependencies include partyserver/partysocket for WebSocket routing, @modelcontextprotocol/sdk for MCP, cron-schedule for scheduling, nanoid for IDs, and zod for schema validation; React integration is an optional peer dependency (@ai-sdk/react, react) consumed via agents/react.

Code Quality - The packages/agents package alone ships 118 *.test.ts files covering core routing, MCP, scheduling, retries, and chat, run via Vitest (including @vitest/browser-playwright for browser-context tests). Naming is consistent (Agent, AgentClient, useAgent) and the retries module (retries.ts) explicitly models Cloudflare-specific transient failure classes (isDurableObjectCodeUpdateReset, isPlatformTransientError), indicating deliberate handling of Durable Object edge cases rather than generic try/catch.

API Design - Getting started is a single npm install agents plus extending the Agent class and adding a Durable Object binding in wrangler.jsonc; the @callable() decorator and useAgent hook let client code call server methods as plain function calls, which is a notably low-boilerplate developer experience for a stateful, real-time system. The large surface area (30+ example apps, many sub-packages) trades off some discoverability for breadth.