cloudflare/agents

Cloudflare Agents – Stateful, server‑side AI / tool agents

What it is – A TypeScript/JavaScript SDK that lets you write Durable Objects on Cloudflare Workers and treat each object as an independent, long‑lived “agent”. An agent has its own persistent storage, can run scheduled jobs, keep WebSocket connections alive, call AI models, act as an MCP (multi‑channel protocol) server or client, and expose type‑safe RPC methods via a @callable() decorator. The runtime automatically hibernates idle agents and wakes them on demand, so you can spin up millions of per‑user or per‑session agents at essentially zero idle cost.

Core concepts

Concept	What it gives you
Persistent state	State lives in a Cloudflare Durable Object and survives restarts; changes are automatically synced to all connected clients.
Callable methods	Decorate class methods with `@callable()` – they become type‑safe RPC endpoints that can be invoked from the browser or other workers.
Sub‑agents	Agents can compose other agents (parent/child) via facets and nested routing, enabling hierarchical workloads.
Scheduling	One‑off, recurring or cron‑style tasks can be scheduled inside an agent.
WebSockets	Real‑time bidirectional channels with lifecycle hooks are built‑in.
AI chat & tools	Built‑in chat layer (`@cloudflare/ai-chat`) that stores messages, supports resumable streaming, and can run child agents as “tools”.
MCP / WebMCP	Agents can expose or consume the Multi‑Channel Protocol (HTTP, SSE, RPC, etc.) and bridge those tools to the browser.
Workflows	Multi‑step, human‑in‑the‑loop processes with pause/resume and approval steps.
Email & Voice	Direct integration with Cloudflare Email Service and voice pipelines (STT/TTS, VAD, SFU).
Code Mode	LLMs can generate TypeScript that calls your tools, and the generated code runs in a sandboxed Worker (`@cloudflare/shell`).
Payments (x402)	Pay‑per‑call APIs can be billed via the x402 protocol.
Observability	Tracing, metrics and structured logs are emitted automatically.
SQL	Agents can execute SQLite queries directly inside the Durable Object.
Frontend hooks	React hooks (`useAgent`, `useAgentChat`, `useVoiceAgent`) and a vanilla‑JS client (`AgentClient`) make integration easy.

Packages in the monorepo

Package	Role
`agents`	Core SDK – agents, routing, scheduling, MCP, workflows, voice, browser agents, etc.
`@cloudflare/ai-chat`	Higher‑level chat abstraction with persistent messages and tool execution.
`@cloudflare/think`	Opinionated chat‑agent base that adds an “agentic loop” and workspace utilities.
`@cloudflare/codemode`	Turns LLM output into executable TypeScript that calls your tools.
`@cloudflare/shell`	Sandboxed JS execution with a virtual filesystem for safe code‑mode runs.
`@cloudflare/voice`	Compatibility wrapper for the voice APIs (deprecated in favour of the core `agents/voice` exports).
`@cloudflare/worker-bundler`	Bundles Workers at runtime, used together with the Worker‑Loader binding.
`hono-agents`	Middleware that adds agents to a Hono web framework app.

Typical use‑cases

Per‑user assistants – One agent per user stores conversation history, preferences, and runs scheduled reminders.
Realtime multiplayer rooms – Each game room is an agent that synchronises state to all players via WebSockets.
Tool‑calling AI assistants – An LLM calls child agents (e.g., a calendar‑agent, a search‑agent) and streams results back to the user.
Workflow automation – Complex multi‑step processes (e.g., ticket triage → human approval → execution) are modelled as durable workflows.
Voice bots – Combine STT/TTS services with an agent that maintains dialogue state and can invoke other tools.
Pay‑per‑call APIs – Expose a function as an x402‑billed endpoint; the agent handles billing and throttling.

Getting started (from the README)

Create a starter project

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

Or add the SDK to an existing Worker
```
npm install agents
```
Write an agent – extend Agent and mark methods with @callable() (see the counter example in the README).
Configure Durable Objects in wrangler.jsonc (binding name, class name, SQLite migration tag).
Deploy with Cloudflare Wrangler as you would any Worker.
Consume from the browser – use the React hook useAgent (or the vanilla AgentClient) to call methods and receive live state updates.

Documentation & learning resources

Full docs – https://developers.cloudflare.com/agents/ (getting‑started guide, API reference, tutorials).
Examples – 30+ self‑contained demos under examples/ (playground, chat assistants, MCP servers/clients, code‑mode, voice pipelines, workflows, etc.).
Design docs – design/ contains architecture decision records and pattern guides (Anthropic patterns, human‑in‑the‑loop, etc.).
OpenAI SDK examples – openai-sdk/ shows how to use the OpenAI Agents JavaScript SDK with Cloudflare agents.

Development workflow (for contributors)

Node 24+, pnpm workspaces, Nx for task orchestration.
Build: pnpm run build (Nx builds packages in dependency order, caches results).
Lint/type‑check: pnpm run check.
Test: pnpm run test (Vitest + Workers runtime) and pnpm run test:react (Playwright React hook tests).
Changes to packages require a changeset (pnpm exec changeset).
External PRs are currently not accepted; the team prefers internal iteration, but issues and discussions are welcome.

License

MIT – permissive open‑source license.

Bottom line – Cloudflare Agents is a production‑grade framework for building stateful, server‑side AI agents that can run at massive scale on Cloudflare’s edge network, with first‑class support for real‑time sync, scheduling, tool‑calling, voice, email, payments and more.

cloudflare/agents