cloudflare/agents

cloudflare/agents

Description: Build and deploy AI Agents on Cloudflare

Language: TypeScript

License: MIT

Stars: 5081

Forks: 588

Open issues: 122

Created: 2025-01-29T23:14:04Z

Pushed: 2026-06-10T22:48:14Z

Default branch: main

Fork: no

Archived: no

README:

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](https://developers.cloudflare.com/agents/) — 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 {
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({
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:

{
"name": "counter",
"main": "server.ts",
"compatibility_date": "2026-01-28",
"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 browser-side tools to agents over WebSocket | | 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 | AgentClient and VoiceClient for non-React environments |

Packages

| Package | Description | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | [agents](packages/agents) | Core SDK — Agent class, routing, state, scheduling, MCP, email, workflows, x402, browser agents | | [@cloudflare/ai-chat](packages/ai-chat) | Higher-level AI chat — persistent messages, resumable streaming, tool execution | | [@cloudflare/think](packages/think) | Opinionated chat agent base — agentic loop, stream resumption, client tools, workspace tools | | [@cloudflare/codemode](packages/codemode) | LLMs write executable code that calls your tools, instead of one tool call at a time | | [@cloudflare/shell](packages/shell) | Sandboxed JS execution + virtual filesystem (Workspace) for agents | | [@cloudflare/voice](packages/voice) | Voice pipeline — STT, TTS, VAD, streaming, SFU utilities | | [@cloudflare/worker-bundler](packages/worker-bundler) | Build and bundle Workers at runtime, for use with the Worker Loader binding | | [hono-agents](packages/hono-agents) | Hono middleware for adding agents to Hono apps |

> AI-chat modules used to live in agents/ai-chat-agent, agents/chat, agents/ai-react, and agents/ai-types. Those entry points still re-export, but they're deprecated — import from @cloudflare/ai-chat directly. New chat-from-scratch projects should look at @cloudflare/think.

Examples

The [examples/](examples) directory has 30+ self-contained demos. A non-exhaustive tour:

• Showcase — [playground/](examples/playground) is the kitchen-sink app: state, callable methods, scheduling, chat, tools, MCP, workflows, email, voice — all in one UI
• Chat & assistants — [assistant/](examples/assistant), [agents-as-tools/](examples/agents-as-tools), [agent-skills/](examples/agent-skills), [workspace-chat/](examples/workspace-chat), [resumable-stream-chat/](examples/resumable-stream-chat),…