+0
Daily
+0
Weekly
+128
Monthly
5,942
stars
823
forks
34
watchers
–
prs
–
issues
424
releases
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