The Cloudflare Agents SDK is a TypeScript library for building stateful agents on Cloudflare Durable Objects. Each agent is its own durable instance with SQLite storage, identity, and lifecycle; it hibernates when idle and wakes on demand, so an application can run millions of them — one per user, session, or game room — with no cost while inactive.
An agent class extends Agent, declares an initial state, and marks methods with the @callable() decorator for type-safe RPC. Calls to setState sync to every connected client automatically, and the useAgent React hook lets a frontend call agent methods as if they were local functions. Because the agent is a Durable Object, it needs a binding and a SQLite migration in the Worker configuration.
The runtime adds scheduling (one-time, recurring, and cron), WebSockets with lifecycle hooks, AI chat with message persistence and resumable streaming, MCP (Model Context Protocol) in both directions over HTTP, SSE, and RPC with elicitation, durable workflows with human-in-the-loop approval, email send and receive, a voice pipeline with speech-to-text, streaming text-to-speech, voice-activity detection and interruption, x402 payments, and built-in tracing, metrics, and structured logs. Code Mode has the model write executable TypeScript that calls your tools instead of issuing one tool call at a time, and that code runs inside an isolated Worker with a virtual filesystem.
The repository is a set of packages layered over the core: @cloudflare/ai-chat for the chat layer, @cloudflare/think as an opinionated chat-agent base with its own agentic loop, @cloudflare/codemode, @cloudflare/shell for sandboxed execution, @cloudflare/voice, @cloudflare/worker-bundler for building Workers at runtime, and hono-agents for Hono apps. Over 30 self-contained examples cover chat, MCP, Code Mode, voice, workflows, payments, and webhooks, and a starter template gets a running agent from three commands.
Features
- Persistent state: state survives restarts and syncs to every connected client
- Callable methods: type-safe RPC through the @callable() decorator
- Sub-agents: parent and child composition via facets, nested routing, and typed parent lookup
- Agent tools: chat-capable sub-agents run as tools with streaming child timelines
- Scheduling: one-time, recurring, and cron-based tasks per agent
- WebSockets: real-time bidirectional communication with lifecycle hooks
- AI chat: message persistence, resumable streaming, and server- or client-side tool execution
- MCP: act as an MCP server or connect as a client over HTTP, SSE, and RPC, with elicitation
- Workflows: durable multi-step tasks with human-in-the-loop approval
- Code Mode and sandboxes: generated TypeScript runs in an isolated Worker with a virtual filesystem
- Voice and email: continuous speech-to-text, streaming text-to-speech, VAD and SFU utilities; send, receive, and reply to mail
- Client libraries: useAgent, useAgentChat, and useVoiceAgent React hooks plus AgentClient for vanilla JavaScript
