Cloudflare Agents

cloudflare-agents · cloudflare/agents · ★ 5.0k · last commit 2026-05-26

Primitive shape

No installable primitives

Summary

Cloudflare Agents — Summary

Cloudflare Agents (agents npm package, v0.13.3, 5k stars, MIT) is a TypeScript SDK for building persistent, stateful AI agents backed by Cloudflare Durable Objects — each agent is a DO instance with its own SQLite storage, WebSocket connections, and lifecycle. The SDK's core value proposition is infinite horizontal scalability: millions of agent instances can run simultaneously, each idle-cost-free, hibernating when inactive and waking on demand. The Agent class extends Durable Object's Server with typed state sync, @callable() RPC decorators for type-safe client calls, scheduling (one-time/recurring/cron), MCP server/client capabilities, durable multi-step workflows with human-in-the-loop approval, WebMCP (browser-side tool exposure), email send/receive, voice (STT/TTS/VAD), browser agent mode, code mode (LLMs generate executable TypeScript instead of tool calls), and sandboxed code execution via @cloudflare/shell. The React hooks (useAgent, useAgentChat, useVoiceAgent) integrate agent state directly into React components with real-time sync. The monorepo ships 30+ example applications and 8 core packages. Compared to seeds, Cloudflare Agents is closest to claude-flow in TypeScript/multi-agent scope, but uniquely targets the Cloudflare Workers runtime (Durable Objects) rather than Node.js — making it the only edge-native agent framework in the catalog.

Overview

Cloudflare Agents — Overview

Origin

Built and maintained by Cloudflare Inc. Released publicly in 2025 as a first-party SDK for building AI agents on Cloudflare's serverless infrastructure (Durable Objects + Workers).

Philosophy

From the README:

"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."

The core philosophy: agents as Durable Objects — the agent model maps directly to Cloudflare's infrastructure primitive. State, storage, and lifecycle are infra primitives, not application logic.

Design pillars

Durable Object = Agent: one agent = one DO instance; state syncs to all connected clients automatically
@callable() decorator: typed RPC — call agent methods from the frontend like local functions
Code Mode: LLMs generate executable TypeScript instead of individual tool calls — dramatically reduces round-trips for complex tasks
Sandboxed execution: @cloudflare/shell provides a virtual filesystem inside a Worker for generated code
WebMCP: expose browser-side capabilities (browser tabs, local files) to cloud-side agents over WebSocket
x402 payments: pay-per-call APIs using the x402 protocol — native monetization

Architecture note

The Cloudflare Agents SDK is built on top of partyserver (real-time DO coordination library). The Agent class extends Server from partyserver with AI-specific capabilities.

Sub-agent composition

Parent/child DO composition via facets, nested routing, and typed parent lookup. Each child DO can be an independent agent.

Architecture

Cloudflare Agents — Architecture

Distribution

Type: npm-package
Package name: agents
Version: 0.13.3
Install: npm install agents
Required runtime: Cloudflare Workers (Durable Objects) — NOT Node.js standalone
License: MIT

Core packages

Package	Description
`agents`	Core SDK — Agent class, routing, state, scheduling, MCP, email, workflows
`@cloudflare/ai-chat`	Higher-level AI chat with persistent messages and resumable streaming
`@cloudflare/think`	Opinionated chat agent base with agentic loop and stream resumption
`@cloudflare/codemode`	LLMs write executable TypeScript instead of tool calls
`@cloudflare/shell`	Sandboxed JS execution + virtual filesystem for agents
`@cloudflare/voice`	Voice pipeline — STT, TTS, VAD, streaming, SFU utilities
`@cloudflare/worker-bundler`	Build and bundle Workers at runtime
`hono-agents`	Hono middleware for adding agents to Hono apps

Deployment configuration (`wrangler.jsonc`)

{
  "name": "my-agent",
  "main": "server.ts",
  "compatibility_date": "2026-01-28",
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
}

Runtime constraints

Cloudflare Workers only: cannot run on Node.js, Deno, or Bun standalone
SQLite via Durable Objects: each agent instance gets its own SQLite database
Web standard APIs only: no Node.js-specific APIs (Buffer, fs, etc.)

CLI (from `package.json` bin field)

"bin": { "agents": "dist/cli/index.js" }

The agents CLI is bundled with the npm package.

React integration

agents/react exports useAgent, useAgentChat, useVoiceAgent hooks for real-time frontend-backend agent state sync.

Components

Cloudflare Agents — Components

Core SDK (`agents` package)

Export	Type	Purpose
`Agent`	class	Base class extending Durable Object Server; core agent primitive
`routeAgentRequest`	function	Route incoming requests to the correct DO agent
`callable`	decorator	Mark agent methods as RPC-accessible from frontend
`getServerByName`	function	Look up named agent DO instance
`MCPClientManager`	class	Manage MCP client connections
`McpAgent`	class	Agent that acts as an MCP server
`AgentEmail`	type	Email send/receive interface
`WorkflowCallback`	type	Durable workflow step definition

React hooks (`agents/react`)

Hook	Purpose
`useAgent`	Subscribe to agent state with auto-sync
`useAgentChat`	Chat interface with message history
`useVoiceAgent`	Voice agent with STT/TTS integration

Feature modules

Module	Purpose
`schedule.ts`	One-time, recurring, cron scheduling
`workflows.ts`	Durable multi-step workflows
`mcp/`	MCP server + client implementation
`email.ts`	Email via Cloudflare Email Service
`browser/`	Browser agent capabilities
`codemode/`	Code generation execution mode
`webmcp`	Browser-side tool exposure over WebSocket
`observability/`	Tracing, metrics, structured logs
`retries.ts`	Retry logic with exponential backoff

Packages with standalone npm identity

@cloudflare/ai-chat, @cloudflare/think, @cloudflare/codemode, @cloudflare/shell, @cloudflare/voice, @cloudflare/worker-bundler, hono-agents

Examples (30+)

Full list includes: playground (kitchen-sink), assistant, agents-as-tools, workspace-chat, resumable-stream-chat, structured-input, dynamic-tools, multi-ai-chat, mcp, mcp-client, mcp-server, mcp-worker, mcp-elicitation, mcp-rpc-transport, webmcp, codemode, voice-agent, voice-input, elevenlabs-starter, workflows, a2a.

Prompts

Cloudflare Agents — Prompts

Verbatim: README feature table (architecture-as-documentation)

| 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, 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                                    |
| **WebMCP**              | Expose browser-side tools to agents over WebSocket                              |
| **Code Mode**           | LLMs generate executable TypeScript instead of individual tool calls            |
| **Sandboxed Execution** | Run generated code inside an isolated Worker with a virtual filesystem          |

Technique: Feature matrix as architectural contract. Each row defines a capability that is either present or absent — no gradations. This serves as both documentation and a spec for what the SDK must deliver.

Verbatim: AGENTS.md (coding agent instructions)

VoltAgent ships AGENTS.md at the repo root targeting AI coding assistants working on the codebase. The Cloudflare Agents repo similarly ships AGENTS.md.

@callable decorator pattern

The @callable() decorator is itself a prompt-injection mechanism: it makes typed TypeScript methods accessible to the LLM as tools, using the method name and JSDoc as the tool name and description. The LLM's "prompt" for tool selection is derived from TypeScript type information.

Uniqueness

Cloudflare Agents — Uniqueness

Differs from seeds

The closest seed architecturally is claude-flow (TypeScript, multi-agent, MCP, SQLite), but Cloudflare Agents is built on Cloudflare Durable Objects — a fundamentally different infrastructure model. While claude-flow is a Node.js CLI with SQLite in the local filesystem, Cloudflare Agents runs at the network edge, scales to millions of instances, and uses DO's built-in SQLite distributed across Cloudflare's global edge. The Code Mode (@cloudflare/codemode) is unique: LLMs generate executable TypeScript instead of making individual tool calls, reducing multi-step task latency. WebMCP (browser-side tool exposure over WebSocket) has no equivalent in any seed. The x402 payment protocol integration is also unique in the catalog.

Positioning

The only edge-native agent framework in this batch and the entire catalog. Targets developers building agent-powered products on Cloudflare's infrastructure where scale, hibernation, and global distribution are requirements. Not suitable for local development or traditional server deployments.

Distinctive features

DO = Agent: Durable Object is the agent runtime primitive — scale to millions, hibernate at zero cost — unique architecture
@callable() decorator: type-safe RPC from TypeScript to TypeScript with full type inference — unique ergonomics
Code Mode: LLMs write executable TypeScript instead of tool calls — reduces round-trips significantly
WebMCP: expose browser-tab capabilities (localStorage, IndexedDB, DOM tools) to cloud agents over WebSocket
x402 payments: built-in per-call monetization — unique in the catalog
Playground: kitchen-sink example app demonstrating every feature

Observable failure modes

Cloudflare lock-in: Durable Objects are a Cloudflare-only primitive; migrating off Cloudflare requires rewriting the agent runtime
Local development friction: wrangler required for all development; no pure Node.js fallback
DO limits: individual DO has a 128MB memory limit; large context windows may exceed it
No Python: TypeScript-only SDK; Python ecosystem users are excluded
Cost model: while hibernation is cheap, high-frequency agents with many active connections can be expensive at scale

Workflow

Cloudflare Agents — Workflow

Basic counter agent

export class CounterAgent extends Agent<Env, CounterState> {
  initialState = { count: 0 };

  @callable()
  increment() {
    this.setState({ count: this.state.count + 1 });
    return this.state.count;
  }
}

// Client side
const agent = useAgent<CounterAgent, CounterState>({
  agent: "CounterAgent",
  onStateUpdate: (state) => setCount(state.count)
});
agent.stub.increment(); // type-safe RPC

Phase	Artifact
1. Extend Agent class, define state + callables	TypeScript class
2. Configure wrangler.jsonc with DO bindings	Deployment config
3. Deploy to Cloudflare Workers	Live DO instance
4. Client connects via useAgent / AgentClient	WebSocket connection
5. State changes broadcast to all connected clients	Real-time sync

Durable workflow

Phase	Artifact
1. Define workflow with step sequence	Workflow definition
2. Each step executes in a DO instance	Durable step result
3. Pause at requireApproval step	Human approval event
4. Resume on approval	Remaining steps execute
5. Final result	Workflow output

AI chat workflow

Phase	Artifact
1. Client sends message via useAgentChat	Message in DO SQLite
2. Agent processes with LLM	Tool calls + response
3. Response streamed to client	Event stream
4. State auto-persisted	SQLite row

Approval gates

Durable workflow requireApproval step — pauses execution until human confirmation received via WebSocket message.

Code mode

LLM generates TypeScript code instead of individual tool calls → @cloudflare/shell executes in sandboxed Worker with virtual filesystem.

Memory Context

Cloudflare Agents — Memory & Context

Memory architecture

Memory is the Durable Object's built-in SQLite database — not an add-on. Each DO instance (each agent) has its own SQLite database that persists across hibernation and restarts.

export class MyAgent extends Agent<Env, MyState> {
  initialState = { data: [] };

  @callable()
  addItem(item: string) {
    this.setState({ data: [...this.state.data, item] });
    // setState writes to DO SQLite automatically
  }
}

State sync

State changes via setState() are:

Persisted to DO SQLite synchronously
Broadcast to all connected WebSocket clients automatically
Available on reconnect without re-fetch

AI chat message history

@cloudflare/ai-chat stores full conversation history in DO SQLite. Messages persist across sessions; no in-memory-only mode.

State files

No local filesystem files — all state lives in Cloudflare's edge-distributed SQLite.

Cross-session handoff

Yes — because state is in DO SQLite, any client that knows the DO instance ID can reconnect and receive the current state. Agent instances are addressed by name (getServerByName("MyAgent", agentId)).

Memory compaction

Not built-in for conversation history. Developers manage message window size in @cloudflare/ai-chat configuration.

Resumable streaming

Separate from memory: in-flight LLM stream state is tracked by run ID. Clients reconnecting to the same run ID receive buffered events from where they disconnected.

Orchestration

Cloudflare Agents — Orchestration

Multi-agent

Yes. Parent/child Durable Object composition via:

Facets: child DOs accessed from parent DO
Nested routing: routeAgentRequest routes sub-requests
Typed parent lookup: child can reference parent DO by type

Sub-agents can also run as tools with streaming child timelines.

Orchestration pattern

hierarchical — parent DO coordinates child DOs. Workflows are sequential with parallel steps possible.

Max concurrent agents

Effectively unlimited — Cloudflare Durable Objects scale to millions of instances. Each instance hibernates when idle (zero cost).

Isolation mechanism

Process — each Durable Object instance runs in its own isolated Worker context with its own memory space. Not a container (lighter weight: V8 isolate isolation).

Multi-model

Yes. AI calls are made via fetch to any model provider API. No predefined role mapping; each agent can use different providers.

Execution mode

event-driven — agents wake on WebSocket connections, HTTP requests, scheduled events, or email.

Crash recovery

Yes — DO state is durable SQLite; agent state survives Worker restarts. Workflows are durable step-by-step.

Context compaction

Not built-in; developer-managed.

Consensus

None.

Prompt chaining

Yes — workflow steps form explicit chains; each step's output is passed to the next.

Code Mode

@cloudflare/codemode — LLMs generate TypeScript code that calls tools directly, rather than making individual tool calls. Dramatically reduces round-trips for complex tasks.

Streaming

Yes — ResumableStream from @cloudflare/ai-chat with client reconnect support.

MCP

Full MCP client/server: McpAgent class serves tools as MCP server; agents connect as MCP clients. Transport: HTTP, SSE, RPC (WebSocket-based), elicitation.

Ui Cli Surface

Cloudflare Agents — UI & CLI Surface

CLI binary

agents — bundled with the npm package (bin: { "agents": "dist/cli/index.js" }).

Also: npm create cloudflare@latest -- --template cloudflare/agents-starter scaffolds a new project.

Playground (kitchen-sink example)

examples/playground/ is a comprehensive React app demonstrating all features: state sync, callable methods, scheduling, chat, tools, MCP, workflows, email, voice — all in a single UI. This is the primary "local dashboard" for development.

React hooks

The primary integration for real-time UI:

// Real-time agent state in React
const agent = useAgent<CounterAgent, CounterState>({
  agent: "CounterAgent",
  onStateUpdate: (state) => setCount(state.count)
});

// Chat interface
const { messages, sendMessage } = useAgentChat({ agent });

// Voice
const voice = useVoiceAgent({ agent });

Vanilla JS client

AgentClient and VoiceClient for non-React environments.

IDE integration

AGENTS.md at repo root
.mcp.json at repo root (MCP server configuration for the codebase)
.vscode/ settings

Observability

observability/ module provides:

Built-in tracing
Metrics
Structured logs

External: Cloudflare Workers dashboard provides DO metrics (request count, CPU time, storage size).

Voice interface

@cloudflare/voice: STT (OpenAI Whisper, custom), TTS (ElevenLabs, Cartesia), VAD (Voice Activity Detection), SFU utilities for multi-party audio.

x402 payments

Native pay-per-call APIs via the x402 protocol — agents can monetize their tools.

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k

A6 Multi-agent orchestrator

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k

A6 Multi-agent orchestrator

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k

A6 Multi-agent orchestrator

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k

A6 Multi-agent orchestrator

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k

A6 Multi-agent orchestrator

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k

A6 Multi-agent orchestrator

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…

Distribution

Type: npm-package
License: MIT
Install: multi-step
Version: 0.13.3

Surfaces

CLI binary: agents
Local UI: web-dashboard
Tech stack: React + TypeScript (playground example app)

Components

Commands: 0
Skills: 0
Subagents: 0
Hooks: 0
MCP servers: 0
MCP tools: 0
Scripts: 2
Templates: 30

Workflow

Phases: 5
Approval gates: 1
Spec format: none
Spec storage: db
Delta or full: none

Orchestration

Multi-agent: Yes
Pattern: hierarchical
Isolation: process
Consensus: none
Prompt chaining: Yes

Multi-model

Multi-model: Yes
BYOK: Yes
Modal: text+vision+audio

Execution

Mode: event-driven
Crash recovery: Yes
Compaction: No
Session handoff: Yes
Streaming: Yes

Memory

Type: sqlite
Persistence: global
Search: none

Quality

TDD: No
TDD mechanism: none
Validators: 2
Self-review: none

Git / Observability

Auto commit: No
Auto PR: No
Auto merge: No
Worktree/feat: No
Audit log: Yes
Audit format: structured-md
Replay: Yes

Tools

Primary: Cloudflare Workers
Targets: 4
Portability: low

Signals

Stars: 5.0k
Last commit: 2026-05-26
Maintainer: active
Quality score: 6.4/10

Summary

Cloudflare Agents — Summary

Overview

Cloudflare Agents — Overview

Origin

Philosophy

Design pillars

Architecture note

Sub-agent composition

Architecture

Cloudflare Agents — Architecture

Distribution

Core packages

Deployment configuration (wrangler.jsonc)

Runtime constraints

CLI (from package.json bin field)

React integration

Components

Cloudflare Agents — Components

Core SDK (agents package)

React hooks (agents/react)

Feature modules

Packages with standalone npm identity

Examples (30+)

Prompts

Cloudflare Agents — Prompts

Verbatim: README feature table (architecture-as-documentation)

Verbatim: AGENTS.md (coding agent instructions)

@callable decorator pattern

Uniqueness

Cloudflare Agents — Uniqueness

Differs from seeds

Positioning

Distinctive features

Observable failure modes

Workflow

Cloudflare Agents — Workflow

Basic counter agent

Durable workflow

AI chat workflow

Approval gates

Code mode

Memory Context

Cloudflare Agents — Memory & Context

Memory architecture

State sync

AI chat message history

State files

Cross-session handoff

Memory compaction

Resumable streaming

Orchestration

Cloudflare Agents — Orchestration

Multi-agent

Orchestration pattern

Max concurrent agents

Isolation mechanism

Multi-model

Execution mode

Crash recovery

Context compaction

Consensus

Prompt chaining

Code Mode

Streaming

MCP

Ui Cli Surface

Cloudflare Agents — UI & CLI Surface

CLI binary

Playground (kitchen-sink example)

React hooks

Vanilla JS client

IDE integration

Observability

Voice interface

x402 payments

Related frameworks

Deployment configuration (`wrangler.jsonc`)

CLI (from `package.json` bin field)

Core SDK (`agents` package)

React hooks (`agents/react`)