Cloudflare Agents

What it is – A TypeScript/JavaScript SDK that lets you build persistent, stateful “agents” on Cloudflare Durable Objects. Each agent runs as its own Durable Object, giving it isolated storage, lifecycle hooks, and the ability to hibernate when idle. The platform adds first‑class support for real‑time sync, scheduling, AI model calls, tool execution, MCP (multi‑channel protocol), voice, email, payments, and more.

Core ideas

Concept	What it gives you
Persistent state	Agents keep data across restarts and automatically sync to every connected client.
@callable() RPC	Decorate class methods; they become type‑safe remote procedures you can invoke from the browser as if they were local functions.
Sub‑agents	Build hierarchies of agents (parent/child) for composition and routing.
Scheduling	One‑off, recurring or cron‑style jobs that run inside the agent.
WebSockets	Bidirectional real‑time channels with lifecycle events.
AI chat & tools	Built‑in chat layer (`@cloudflare/ai-chat`) that stores messages, supports resumable streaming, and can run other agents as tools.
MCP / WebMCP	Generic multi‑channel protocol for HTTP, SSE, RPC, or browser‑side tool bridging.
Workflows	Multi‑step durable tasks that can pause for human approval.
Voice & Email	Streaming speech‑to‑text / text‑to‑speech pipelines and integration with Cloudflare Email Service.
Payments (x402)	Pay‑per‑call APIs via the x402 protocol.
Observability	Tracing, metrics, and structured logs baked in.
SQLite	Direct queries against a per‑agent SQLite DB.
React hooks & vanilla client	`useAgent`, `useAgentChat`, `useVoiceAgent` for React; `AgentClient` for plain JS.

Typical use cases

Per‑user or per‑session state – e.g., a personal assistant that remembers a user’s preferences across visits.
Realtime collaborative apps – game rooms, shared whiteboards, or dashboards where every client sees the same state instantly.
AI‑driven assistants – chat agents that call LLMs, keep conversation history, and invoke tool agents (search, database, etc.).
Scheduled background work – reminders, periodic data pulls, or cron‑style jobs that run close to the user’s data.
Voice bots – end‑to‑end speech pipelines that can stream audio to/from the agent.
Workflow engines – multi‑step processes that need human‑in‑the‑loop approvals.
Pay‑per‑use APIs – expose a function as an x402‑priced endpoint.

Getting started (quick steps)

Create a project

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

Add the SDK to an existing repo
```
npm install agents
```
Write an agent – extend Agent and mark methods with @callable() (see the README counter example).
Configure Durable Objects in wrangler.jsonc (binding name, class name, and SQLite migration if needed).
Deploy with wrangler publish (standard Cloudflare Workers workflow).
Consume from the frontend – use the useAgent React hook or the vanilla AgentClient to call methods and receive live state updates.

Packages in the monorepo

Package	Role
`agents`	Core SDK – agents, routing, scheduling, MCP, workflows, etc.
`@cloudflare/ai-chat`	High‑level chat abstraction with persistence and tool execution.
`@cloudflare/think`	Opinionated “agentic loop” base for building chat assistants.
`@cloudflare/codemode`	Lets LLMs generate executable TypeScript that runs inside a sandboxed Worker.
`@cloudflare/worker-bundler`	Bundles Workers at runtime for dynamic code loading.
`hono-agents`	Middleware to attach agents to a Hono web framework app.
(Deprecated) `@cloudflare/shell`, `@cloudflare/voice`	Compatibility wrappers for older APIs.

Documentation & learning resources

Full docs – https://developers.cloudflare.com/agents/ (getting started, API reference, guides).
Examples – 30+ demos under examples/ (playground, chat assistants, MCP, voice pipelines, workflows, payments, games, etc.).
Guides – Anthropic patterns, human‑in‑the‑loop workflows, design decisions in design/.
OpenAI SDK examples – openai-sdk/ shows how to use the OpenAI Agents JS SDK together with Cloudflare Agents.

Who maintains it?

Developed by Cloudflare. The repo uses pnpm workspaces with Nx for builds and testing. Contributions are limited to internal contributors for now, but issues and discussions are open to the community.

License

MIT (see LICENSE).

cloudflare/agents

Cloudflare Agents