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.

Features

| Feature | Description | | --------------------- | ---------------------------------------------------------------------- | | Persistent State | Syncs to all connected clients, survives restarts | | Callable Methods | Type-safe RPC via the @callable() decorator | | 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 | | Workflows | Durable multi-step tasks with human-in-the-loop approval | | Email | Receive and respond via Cloudflare Email Routing | | Code Mode | LLMs generate executable TypeScript instead of individual tool calls | | SQL | Direct SQLite queries via Durable Objects | | React Hooks | useAgent and useAgentChat for frontend integration | | Vanilla JS Client | AgentClient for non-React environments |

Coming soon: Realtime voice agents, web browsing (headless browser), sandboxed code execution, and multi-channel communication (SMS, messengers).

Packages

| Package | Description | | ------------------------------------------- | ------------------------------------------------------------------------------- | | agents | Core SDK — Agent class, routing, state, scheduling, MCP, email, workflows | | @cloudflare/ai-chat | Higher-level AI chat — persistent messages, resumable streaming, tool execution | | hono-agents | Hono middleware for adding agents to Hono apps | | @cloudflare/codemode | Experimental — LLMs write executable code to orchestrate tools |

Examples

The examples/ directory has self-contained demos covering most SDK features — MCP servers/clients, workflows, email agents, webhooks, tic-tac-toe, resumable streaming, and more. The playground is the kitchen-sink showcase with everything in one UI.

There are also examples using the OpenAI Agents SDK in openai-sdk/.

Run any example locally:

cd examples/playground
npm run dev

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

Repository Structure

| Directory | Description | | ----------------------------------------------- | -------------------------------------------------------- | | packages/agents/ | Core SDK | | packages/ai-chat/ | AI chat layer | | packages/hono-agents/ | Hono integration | | packages/codemode/ | Code Mode (experimental) | | examples/ | Self-contained demo apps | | 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. Uses npm workspaces.

npm install          # install all workspaces
npm run build        # build all packages
npm run check        # full CI check (format, lint, typecheck, exports)
CI=true npm test     # run tests (vitest + vitest-pool-workers)

Changes to packages/ need a changeset:

npx 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