Cloudflare Agents

June 5, 2026 · View on GitHub

npm version npm downloads

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-01-28",
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "name": "CounterAgent", "class_name": "CounterAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["CounterAgent"] }]
}

Features

FeatureDescription
Persistent StateSyncs to all connected clients, survives restarts
Callable MethodsType-safe RPC via the @callable() decorator
Sub-agentsParent/child DO composition via facets, nested routing, and typed parent lookup
Agent ToolsRun chat-capable sub-agents as tools with streaming child timelines
SchedulingOne-time, recurring, and cron-based tasks
WebSocketsReal-time bidirectional communication with lifecycle hooks
AI ChatMessage persistence, resumable streaming, server/client tool execution
MCPAct as MCP servers or connect as MCP clients (HTTP, SSE, RPC, elicitation)
WebMCPExpose browser-side tools to agents over WebSocket
WorkflowsDurable multi-step tasks with human-in-the-loop approval
EmailSend, receive, and reply via Cloudflare Email Service
VoiceContinuous STT, streaming TTS, VAD, interruption, SFU utilities
Browser AgentsRun agents in the browser tab with agents/browser
Code ModeLLMs generate executable TypeScript instead of individual tool calls
Sandboxed ExecutionRun generated code inside an isolated Worker with a virtual filesystem
x402 PaymentsPay-per-call APIs and tools via the x402 protocol
ObservabilityBuilt-in tracing, metrics, and structured logs
SQLDirect SQLite queries via Durable Objects
React HooksuseAgent, useAgentChat, useVoiceAgent for frontend integration
Vanilla JS ClientAgentClient and VoiceClient for non-React environments

Packages

PackageDescription
agentsCore SDK — Agent class, routing, state, scheduling, MCP, email, workflows, x402, browser agents
@cloudflare/ai-chatHigher-level AI chat — persistent messages, resumable streaming, tool execution
@cloudflare/thinkOpinionated chat agent base — agentic loop, stream resumption, client tools, workspace tools
@cloudflare/codemodeLLMs write executable code that calls your tools, instead of one tool call at a time
@cloudflare/shellSandboxed JS execution + virtual filesystem (Workspace) for agents
@cloudflare/voiceVoice pipeline — STT, TTS, VAD, streaming, SFU utilities
@cloudflare/worker-bundlerBuild and bundle Workers at runtime, for use with the Worker Loader binding
hono-agentsHono 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:

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

DirectoryDescription
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/Voice pipeline
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:

License

MIT