README

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.

sh
npm create cloudflare@latest -- --template cloudflare/agents-starter


Or add to an existing project:

sh
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:

typescript
// server.ts
import { Agent, routeAgentRequest, callable } from "agents";

export type CounterState = { count: number };

export class CounterAgent extends Agent {
  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 })
    );
  }
};


tsx
// 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({
    agent: "CounterAgent",
    onStateUpdate: (state) = setCount(state.count)
  });

  return (
    
      {count}
       agent.stub.increment()}+
       agent.stub.decrement()}-
    
  );
}


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:

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 w