Cloudflare Agents
Agents are persistent, stateful execution environments for agentic workloads, powered by Cloudflare Durable Objects. Each agent has its own state, storage, and lifecycle — with built-in support for real-time communication, scheduling, AI model calls, MCP, workflows, and more.
Agents hibernate when idle and wake on demand. You can run millions of them — one per user, per session, per game room — each costs nothing when inactive.
npm create cloudflare@latest -- --template cloudflare/agents-starter
Or add to an existing project:
npm install agents
Read the docs — getting started, API reference, guides, and more.
Quick Example
A counter agent with persistent state, callable methods, and real-time sync to a React frontend:
// server.ts
import { Agent, routeAgentRequest, callable } from "agents";
export type CounterState = { count: number };
export class CounterAgent extends Agent<Env, CounterState> {
initialState = { count: 0 };
@callable()
increment() {
this.setState({ count: this.state.count + 1 });
return this.state.count;
}
@callable()
decrement() {
this.setState({ count: this.state.count - 1 });
return this.state.count;
}
}
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
return (
(await routeAgentRequest(request, env)) ??
new Response("Not found", { status: 404 })
);
}
};
// client.tsx
import { useAgent } from "agents/react";
import { useState } from "react";
import type { CounterAgent, CounterState } from "./server";
function Counter() {
const [count, setCount] = useState(0);
const agent = useAgent<CounterAgent, CounterState>({
agent: "CounterAgent",
onStateUpdate: (state) => setCount(state.count)
});
return (
<div>
<span>{count}</span>
<button onClick={() => agent.stub.increment()}>+</button>
<button onClick={() => agent.stub.decrement()}>-</button>
</div>
);
}
State changes sync to all connected clients automatically. Call methods like they're local functions.
The agent is a Durable Object, so it needs a binding and a SQLite migration in wrangler.jsonc:
{
"name": "counter",
"main": "server.ts",
"compatibility_date": "2026-06-11",
"compatibility_flags": ["nodejs_compat"],
"durable_objects": {
"bindings": [{ "name": "CounterAgent", "class_name": "CounterAgent" }]
},
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["CounterAgent"] }]
}
Features
| Feature | Description |
|---|
| Persistent State | Syncs to all connected clients, survives restarts |
| Callable Methods | Type-safe RPC via the @callable() decorator |
| Sub-agents | Parent/child DO composition via facets, nested routing, and typed parent lookup |
| Agent Tools | Run chat-capable sub-agents as tools with streaming child timelines |
| Scheduling | One-time, recurring, and cron-based tasks |
| WebSockets | Real-time bidirectional communication with lifecycle hooks |
| AI Chat | Message persistence, resumable streaming, server/client tool execution |
| MCP | Act as MCP servers or connect as MCP clients (HTTP, SSE, RPC, elicitation) |
| WebMCP | Expose page-local tools or bridge remote MCP tools to browser agents |
| Workflows | Durable multi-step tasks with human-in-the-loop approval |
| Email | Send, receive, and reply via Cloudflare Email Service |
| Voice | Continuous STT, streaming TTS, VAD, interruption, SFU utilities |
| Browser Agents | Run agents in the browser tab with agents/browser |
| Code Mode | LLMs generate executable TypeScript instead of individual tool calls |
| Sandboxed Execution | Run generated code inside an isolated Worker with a virtual filesystem |
| x402 Payments | Pay-per-call APIs and tools via the x402 protocol |
| Observability | Built-in tracing, metrics, and structured logs |
| SQL | Direct SQLite queries via Durable Objects |
| React Hooks | useAgent, useAgentChat, useVoiceAgent for frontend integration |
| Vanilla JS Client |
Packages
| Package | Description |
|---|
agents | Core SDK — Agents, routing, Voice, Channels, scheduling, MCP, workflows, x402, browser agents |
@cloudflare/ai-chat | Higher-level AI chat — persistent messages, resumable streaming, tool execution |
@cloudflare/think | Opinionated chat agent base — agentic loop, stream resumption, client tools, workspace tools |
@cloudflare/codemode | LLMs write executable code that calls your tools, instead of one tool call at a time |
@cloudflare/shell | Deprecated: use @cloudflare/computer workspaces |
@cloudflare/voice | Deprecated compatibility wrapper for the agents/voice exports |
@cloudflare/worker-bundler | Build and bundle Workers at runtime, for use with the Worker Loader binding |
hono-agents | Hono middleware for adding agents to Hono apps |
AI-chat modules used to live in agents/ai-chat-agent, agents/chat, agents/ai-react, and agents/ai-types. Those entry points still re-export, but they're deprecated — import from @cloudflare/ai-chat directly. New chat-from-scratch projects should look at @cloudflare/think.
Examples
The examples/ directory has 30+ self-contained demos. A non-exhaustive tour:
- Showcase —
playground/ is the kitchen-sink app: state, callable methods, scheduling, chat, tools, MCP, workflows, email, voice — all in one UI
- Chat & assistants —
agents-as-tools/, computer-skills/, r2-skills/, workspace-chat/, resumable-stream-chat/, structured-input/, dynamic-tools/, multi-ai-chat/, context-overflow-recovery/
- MCP —
mcp/, mcp-client/, mcp-server/, , , , , , ,
Examples using the OpenAI Agents SDK live in openai-sdk/. Work-in-progress experiments live in experimental/ (no stability guarantees).
Run any example locally:
cd examples/playground
npm start
Documentation
- Full docs on developers.cloudflare.com
docs/ directory in this repo (synced upstream)- Anthropic Patterns guide — sequential, routing, parallel, orchestrator, evaluator
- Human-in-the-Loop guide — approval workflows with pause/resume
design/ — architecture and design decision records (chat API, sub-agents, agent tools, workspace, voice, browser tools, retries, and more)
Repository Structure
Development
Node 24+ required. pnpm workspaces with Nx for task orchestration, caching, and affected detection.
pnpm install # install all workspaces
pnpm run build # build all packages (Nx, cached, dependency-ordered)
pnpm run check # sherif + export checks + oxfmt + oxlint + typecheck
pnpm run test # vitest + vitest-pool-workers (Workers runtime)
pnpm run test:react # Playwright-based React hook tests
pnpm exec nx affected -t build # build only what changed
pnpm exec nx affected -t test # test only what changed
Changes to packages/ need a changeset:
pnpm exec changeset
See AGENTS.md for deeper contributor guidance.
Contributing
We are not accepting external pull requests at this time — the SDK is evolving quickly and we want to keep the surface area manageable. That said, we'd love to hear from you:
License
MIT
