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

This is the beginning of the README. Read the rest at the original. Read the full README ↗