Cloudflare Agents

!npm install 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 | AgentClient and VoiceClient for non-React environments |

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 | Sandboxed JS execution + virtual filesystem (Workspace) for agents | | @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 — assistant/, agents-as-tools/, agent-skills/, workspace-chat/, resumable-stream-chat/, structured-input/, dynamic-tools/, multi-ai-chat/, context-overflow-recovery/
• MCP — mcp/, mcp-client/, mcp-server/, mcp-worker/, mcp-worker-authenticated/, mcp-elicitation-mrtr/, mcp-elicitation/, mcp-rpc-transport/, webmcp/, webmcp-react/
• Code Mode & sandboxes — codemode/, codemode-mcp/, codemode-mcp-openapi/, dynamic-workers/, dynamic-workers-playground/, worker-bundler-playground/
• Voice — voice-agent/ is the unified voice pipeline example with Workers AI, AssemblyAI, Telnyx, and ElevenLabs STT; voice-input/ covers dictation; telnyx-voice-agent/ covers phone transport; elevenlabs-starter/ covers broader ElevenLabs media APIs
• Workflows & approvals — workflows/, a2a/
• Auth, payments, comms — auth-agent/, channels/, cross-domain/, x402/, x402-mcp/, email-agent/, github-webhook/, push-notifications/
• Game & misc — tictactoe/, ai-chat/

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

| Directory | Description | | ----------------------------------------------------- | -------------------------------------------------------- | | packages/agents/ | Core SDK | | packages/ai-chat/ | AI chat layer | | packages/think/ | Opinionated chat agent base | | packages/codemode/ | Code Mode | | packages/shell/ | Sandboxed execution + filesystem | | packages/voice/ | Deprecated Voice compatibility wrapper | | packages/worker-bundler/ | Runtime Workers bundler | | packages/hono-agents/ | Hono integration | | examples/ | Self-contained demo apps | | experimental/ | Work-in-progress experiments (not published) | | openai-sdk/ | Examples using the OpenAI Agents SDK | | guides/ | In-depth pattern tutorials | | docs/ | Markdown docs synced to developers.cloudflare.com | | site/ | Deployed websites (agents.cloudflare.com, AI playground) | | design/ | Architecture and design decision records | | scripts/ | Repo-wide tooling |

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:

• Bug reports & feature requests — open an issue
• Questions & ideas — start a discussion

License

MIT