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.

License

MIT