Cloudflare Agents SDK
Your knowledge of the Agents SDK may be outdated. Prefer retrieval over pre-training for any Agents SDK task.
Retrieval Sources
Cloudflare docs: https://developers.cloudflare.com/agents/
| Topic |
Docs URL |
Use for |
| Getting started |
Quick start |
First agent, project setup |
| Adding to existing project |
Add to existing project |
Install into existing Workers app |
| Configuration |
Configuration |
wrangler.jsonc, bindings, assets, deployment |
| Agent class |
Agents API |
Agent lifecycle, patterns, pitfalls |
| State |
Store and sync state |
setState, validateStateChange, persistence |
| Routing |
Routing |
URL patterns, routeAgentRequest |
| Callable methods |
Callable methods |
@callable, RPC, streaming, timeouts |
| Scheduling |
Schedule tasks |
schedule(), scheduleEvery(), cron |
| Workflows |
Run workflows |
AgentWorkflow, durable multi-step tasks |
| HTTP/WebSockets |
WebSockets |
Lifecycle hooks, hibernation |
| Chat agents |
Chat agents |
AIChatAgent, streaming, tools, persistence |
| Client SDK |
Client SDK |
useAgent, useAgentChat, React hooks |
| Client tools |
Client tools |
Client-side tools, autoContinueAfterToolResult |
| Server-driven messages |
Trigger patterns |
saveMessages, waitUntilStable, server-initiated turns |
| Resumable streaming |
Resumable streaming |
Stream recovery on disconnect |
| Email |
Email |
Email routing, secure reply resolver |
| MCP client |
MCP client |
Connecting to MCP servers |
| MCP server |
MCP server |
Building MCP servers with McpAgent |
| MCP transports |
MCP transports |
Streamable HTTP, SSE, RPC transport options |
| Securing MCP servers |
Securing MCP |
OAuth, proxy MCP, hardening |
| Human-in-the-loop |
Human-in-the-loop |
Approval flows, needsApproval, workflows |
| Durable execution |
Durable execution |
runFiber(), stash(), surviving DO eviction |
| Queue |
Queue |
Built-in FIFO queue, queue() |
| Retries |
Retries |
this.retry(), backoff/jitter |
| Observability |
Observability |
Diagnostics-channel events |
| Push notifications |
Push notifications |
Web Push + VAPID from agents |
| Webhooks |
Webhooks |
Receiving external webhooks |
| Cross-domain auth |
Cross-domain auth |
WebSocket auth, tokens, CORS |
| Readonly connections |
Readonly |
shouldConnectionBeReadonly |
| Voice |
Voice |
Experimental STT/TTS, withVoice |
| Browse the web |
Browser tools |
Experimental CDP browser automation |
| Think |
Think |
Experimental higher-level chat agent class |
| Migrations |
AI SDK v5, AI SDK v6 |
Upgrading @cloudflare/ai-chat |
Capabilities
The Agents SDK provides:
- Persistent state — SQLite-backed, auto-synced to clients via
setState
- Callable RPC —
@callable() methods invoked over WebSocket
- Scheduling — One-time, recurring (
scheduleEvery), and cron tasks
- Workflows — Durable multi-step background processing via
AgentWorkflow
- Durable execution —
runFiber() / stash() for work that survives DO eviction
- Queue — Built-in FIFO queue with retries via
queue()
- Retries —
this.retry() with exponential backoff and jitter
- MCP integration — Connect to MCP servers or build your own with
McpAgent
- Email handling — Receive and reply to emails with secure routing
- Streaming chat —
AIChatAgent with resumable streams, message persistence, tools
- Server-driven messages —
saveMessages, waitUntilStable for proactive agent turns
- React hooks —
useAgent, useAgentChat for client apps
- Observability —
diagnostics_channel events for state, RPC, schedule, lifecycle
- Push notifications — Web Push + VAPID delivery from agents
- Webhooks — Receive and verify external webhooks
- Voice (experimental) — STT/TTS via
@cloudflare/voice
- Browser tools (experimental) — CDP-powered browsing via
agents/browser
- Think (experimental) — Higher-level chat agent via
@cloudflare/think
FIRST: Verify Installation
npm ls agents # Should show agents package
If not installed:
npm install agents
For chat agents:
npm install agents @cloudflare/ai-chat ai @ai-sdk/react
Wrangler Configuration
{
"compatibility_flags": ["nodejs_compat"],
"durable_objects": {
"bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
},
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
}
Gotchas:
- Do NOT enable
experimentalDecorators in tsconfig (breaks @callable)
- Never edit old migrations — always add new tags
- Each agent class needs its own DO binding + migration entry
- Add
"ai": { "binding": "AI" } for Workers AI
Agent Class
import { Agent, routeAgentRequest, callable } from "agents";
type State = { count: number };
export class Counter extends Agent<Env, State> {
initialState = { count: 0 };
validateStateChange(nextState: State, source: Connection | "server") {
if (nextState.count < 0) throw new Error("Count cannot be negative");
}
onStateUpdate(state: State, source: Connection | "server") {
console.log("State updated:", state);
}
@callable()
increment() {
this.setState({ count: this.state.count + 1 });
return this.state.count;
}
}
export default {
fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
};
Routing
Requests route to /agents/{agent-name}/{instance-name}:
| Class |
URL |
Counter |
/agents/counter/user-123 |
ChatRoom |
/agents/chat-room/lobby |
Client: useAgent({ agent: "Counter", name: "user-123" })
Custom routing: use getAgentByName(env.MyAgent, "instance-id") then agent.fetch(request).
Core APIs
| Task |
API |
| Read state |
this.state.count |
| Write state |
this.setState({ count: 1 }) |
| SQL query |
this.sql`SELECT * FROM users WHERE id = ${id}` |
| Schedule (delay) |
await this.schedule(60, "task", payload) |
| Schedule (cron) |
await this.schedule("0 * * * *", "task", payload) |
| Schedule (interval) |
await this.scheduleEvery(30, "poll") |
| RPC method |
@callable() myMethod() { ... } |
| Streaming RPC |
@callable({ streaming: true }) stream(res) { ... } |
| Start workflow |
await this.runWorkflow("ProcessingWorkflow", params) |
| Durable fiber |
await this.runFiber("name", async (ctx) => { ... }) |
| Enqueue work |
this.queue("handler", payload) |
| Retry with backoff |
await this.retry(fn, { maxAttempts: 5 }) |
| Broadcast to clients |
this.broadcast(message) |
| Get connections |
this.getConnections(tag?) |
React Client
import { useAgent } from "agents/react";
function App() {
const [state, setLocalState] = useState({ count: 0 });
const agent = useAgent({
agent: "Counter",
name: "my-instance",
onStateUpdate: (newState) => setLocalState(newState),
onIdentity: (name, agentType) => console.log(`Connected to ${name}`)
});
return (
<button => agent.setState({ count: state.count + 1 })}>
Count: {state.count}
</button>
);
}
References
Core
- references/state-scheduling.md — State persistence, scheduling, SQL
- references/callable.md — RPC methods, streaming, timeouts
- references/routing.md — URL patterns, custom routing,
getAgentByName
- references/configuration.md — Wrangler config, bindings, Vite setup
Chat & Streaming
- references/streaming-chat.md — AIChatAgent, resumable streams, tools
- references/client-sdk.md —
useAgent, useAgentChat, AgentClient
- references/server-driven-messages.md — Trigger patterns,
saveMessages
- references/human-in-the-loop.md — Approval flows,
needsApproval
Background Processing
- references/workflows.md — Durable Workflows integration
- references/durable-execution.md —
runFiber, stash, surviving eviction
- references/queue-retries.md — Built-in queue, retry with backoff
Integrations
- references/mcp.md — MCP client and server, transports, securing
- references/email.md — Email routing and handling
- references/webhooks-push.md — Webhooks, push notifications
- references/observability.md — Diagnostics-channel events
Experimental
- references/think.md —
@cloudflare/think higher-level chat agent
- references/voice.md —
@cloudflare/voice STT/TTS
- references/codemode.md — Code Mode for tool orchestration
- references/browse-the-web.md — CDP browser tools
1---2name: agents-sdk3description: Build AI agents on Cloudflare Workers using the Agents SDK. Load when creating stateful agents, durable workflows, real-time WebSocket apps, scheduled tasks, MCP servers, chat applications, voice agents, or browser automation. Covers Agent class, state management, callable RPC, Workflows, durable execution, queues, retries, observability, and React hooks. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.4metadata:5 source: https://skillmd.com/skills/cloudflare/agents-sdk6---78# Cloudflare Agents SDK910Your knowledge of the Agents SDK may be outdated. **Prefer retrieval over pre-training** for any Agents SDK task.1112## Retrieval Sources1314Cloudflare docs: https://developers.cloudflare.com/agents/1516| Topic | Docs URL | Use for |17|-------|----------|---------|18| Getting started | [Quick start](https://developers.cloudflare.com/agents/getting-started/quick-start/) | First agent, project setup |19| Adding to existing project | [Add to existing project](https://developers.cloudflare.com/agents/getting-started/add-to-existing-project/) | Install into existing Workers app |20| Configuration | [Configuration](https://developers.cloudflare.com/agents/api-reference/configuration/) | `wrangler.jsonc`, bindings, assets, deployment |21| Agent class | [Agents API](https://developers.cloudflare.com/agents/api-reference/agents-api/) | Agent lifecycle, patterns, pitfalls |22| State | [Store and sync state](https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/) | `setState`, `validateStateChange`, persistence |23| Routing | [Routing](https://developers.cloudflare.com/agents/api-reference/routing/) | URL patterns, `routeAgentRequest` |24| Callable methods | [Callable methods](https://developers.cloudflare.com/agents/api-reference/callable-methods/) | `@callable`, RPC, streaming, timeouts |25| Scheduling | [Schedule tasks](https://developers.cloudflare.com/agents/api-reference/schedule-tasks/) | `schedule()`, `scheduleEvery()`, cron |26| Workflows | [Run workflows](https://developers.cloudflare.com/agents/api-reference/run-workflows/) | `AgentWorkflow`, durable multi-step tasks |27| HTTP/WebSockets | [WebSockets](https://developers.cloudflare.com/agents/api-reference/websockets/) | Lifecycle hooks, hibernation |28| Chat agents | [Chat agents](https://developers.cloudflare.com/agents/api-reference/chat-agents/) | `AIChatAgent`, streaming, tools, persistence |29| Client SDK | [Client SDK](https://developers.cloudflare.com/agents/api-reference/client-sdk/) | `useAgent`, `useAgentChat`, React hooks |30| Client tools | [Client tools](https://developers.cloudflare.com/agents/api-reference/client-tools/) | Client-side tools, `autoContinueAfterToolResult` |31| Server-driven messages | [Trigger patterns](https://developers.cloudflare.com/agents/api-reference/trigger-patterns/) | `saveMessages`, `waitUntilStable`, server-initiated turns |32| Resumable streaming | [Resumable streaming](https://developers.cloudflare.com/agents/api-reference/resumable-streaming/) | Stream recovery on disconnect |33| Email | [Email](https://developers.cloudflare.com/agents/api-reference/email/) | Email routing, secure reply resolver |34| MCP client | [MCP client](https://developers.cloudflare.com/agents/api-reference/mcp-client-api/) | Connecting to MCP servers |35| MCP server | [MCP server](https://developers.cloudflare.com/agents/api-reference/mcp-agent-api/) | Building MCP servers with `McpAgent` |36| MCP transports | [MCP transports](https://developers.cloudflare.com/agents/api-reference/mcp-transports/) | Streamable HTTP, SSE, RPC transport options |37| Securing MCP servers | [Securing MCP](https://developers.cloudflare.com/agents/api-reference/securing-mcp-servers/) | OAuth, proxy MCP, hardening |38| Human-in-the-loop | [Human-in-the-loop](https://developers.cloudflare.com/agents/concepts/human-in-the-loop/) | Approval flows, `needsApproval`, workflows |39| Durable execution | [Durable execution](https://developers.cloudflare.com/agents/api-reference/durable-execution/) | `runFiber()`, `stash()`, surviving DO eviction |40| Queue | [Queue](https://developers.cloudflare.com/agents/api-reference/queue-tasks/) | Built-in FIFO queue, `queue()` |41| Retries | [Retries](https://developers.cloudflare.com/agents/api-reference/retries/) | `this.retry()`, backoff/jitter |42| Observability | [Observability](https://developers.cloudflare.com/agents/api-reference/observability/) | Diagnostics-channel events |43| Push notifications | [Push notifications](https://developers.cloudflare.com/agents/api-reference/push-notifications/) | Web Push + VAPID from agents |44| Webhooks | [Webhooks](https://developers.cloudflare.com/agents/api-reference/webhooks/) | Receiving external webhooks |45| Cross-domain auth | [Cross-domain auth](https://developers.cloudflare.com/agents/api-reference/cross-domain-authentication/) | WebSocket auth, tokens, CORS |46| Readonly connections | [Readonly](https://developers.cloudflare.com/agents/api-reference/readonly-connections/) | `shouldConnectionBeReadonly` |47| Voice | [Voice](https://developers.cloudflare.com/agents/api-reference/voice/) | Experimental STT/TTS, `withVoice` |48| Browse the web | [Browser tools](https://developers.cloudflare.com/agents/api-reference/browse-the-web/) | Experimental CDP browser automation |49| Think | [Think](https://developers.cloudflare.com/agents/api-reference/think/) | Experimental higher-level chat agent class |50| Migrations | [AI SDK v5](https://developers.cloudflare.com/agents/guides/migration-to-ai-sdk-v5/), [AI SDK v6](https://developers.cloudflare.com/agents/guides/migration-to-ai-sdk-v6/) | Upgrading `@cloudflare/ai-chat` |5152## Capabilities5354The Agents SDK provides:5556- **Persistent state** — SQLite-backed, auto-synced to clients via `setState`57- **Callable RPC** — `@callable()` methods invoked over WebSocket58- **Scheduling** — One-time, recurring (`scheduleEvery`), and cron tasks59- **Workflows** — Durable multi-step background processing via `AgentWorkflow`60- **Durable execution** — `runFiber()` / `stash()` for work that survives DO eviction61- **Queue** — Built-in FIFO queue with retries via `queue()`62- **Retries** — `this.retry()` with exponential backoff and jitter63- **MCP integration** — Connect to MCP servers or build your own with `McpAgent`64- **Email handling** — Receive and reply to emails with secure routing65- **Streaming chat** — `AIChatAgent` with resumable streams, message persistence, tools66- **Server-driven messages** — `saveMessages`, `waitUntilStable` for proactive agent turns67- **React hooks** — `useAgent`, `useAgentChat` for client apps68- **Observability** — `diagnostics_channel` events for state, RPC, schedule, lifecycle69- **Push notifications** — Web Push + VAPID delivery from agents70- **Webhooks** — Receive and verify external webhooks71- **Voice** (experimental) — STT/TTS via `@cloudflare/voice`72- **Browser tools** (experimental) — CDP-powered browsing via `agents/browser`73- **Think** (experimental) — Higher-level chat agent via `@cloudflare/think`7475## FIRST: Verify Installation7677```bash78npm ls agents # Should show agents package79```8081If not installed:82```bash83npm install agents84```8586For chat agents:87```bash88npm install agents @cloudflare/ai-chat ai @ai-sdk/react89```9091## Wrangler Configuration9293```jsonc94{95 "compatibility_flags": ["nodejs_compat"],96 "durable_objects": {97 "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]98 },99 "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]100}101```102103**Gotchas:**104- Do NOT enable `experimentalDecorators` in tsconfig (breaks `@callable`)105- Never edit old migrations — always add new tags106- Each agent class needs its own DO binding + migration entry107- Add `"ai": { "binding": "AI" }` for Workers AI108109## Agent Class110111```typescript112import { Agent, routeAgentRequest, callable } from "agents";113114type State = { count: number };115116export class Counter extends Agent<Env, State> {117 initialState = { count: 0 };118119 validateStateChange(nextState: State, source: Connection | "server") {120 if (nextState.count < 0) throw new Error("Count cannot be negative");121 }122123 onStateUpdate(state: State, source: Connection | "server") {124 console.log("State updated:", state);125 }126127 @callable()128 increment() {129 this.setState({ count: this.state.count + 1 });130 return this.state.count;131 }132}133134export default {135 fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })136};137```138139## Routing140141Requests route to `/agents/{agent-name}/{instance-name}`:142143| Class | URL |144|-------|-----|145| `Counter` | `/agents/counter/user-123` |146| `ChatRoom` | `/agents/chat-room/lobby` |147148Client: `useAgent({ agent: "Counter", name: "user-123" })`149150Custom routing: use `getAgentByName(env.MyAgent, "instance-id")` then `agent.fetch(request)`.151152## Core APIs153154| Task | API |155|------|-----|156| Read state | `this.state.count` |157| Write state | `this.setState({ count: 1 })` |158| SQL query | `` this.sql`SELECT * FROM users WHERE id = ${id}` `` |159| Schedule (delay) | `await this.schedule(60, "task", payload)` |160| Schedule (cron) | `await this.schedule("0 * * * *", "task", payload)` |161| Schedule (interval) | `await this.scheduleEvery(30, "poll")` |162| RPC method | `@callable() myMethod() { ... }` |163| Streaming RPC | `@callable({ streaming: true }) stream(res) { ... }` |164| Start workflow | `await this.runWorkflow("ProcessingWorkflow", params)` |165| Durable fiber | `await this.runFiber("name", async (ctx) => { ... })` |166| Enqueue work | `this.queue("handler", payload)` |167| Retry with backoff | `await this.retry(fn, { maxAttempts: 5 })` |168| Broadcast to clients | `this.broadcast(message)` |169| Get connections | `this.getConnections(tag?)` |170171## React Client172173```tsx174import { useAgent } from "agents/react";175176function App() {177 const [state, setLocalState] = useState({ count: 0 });178179 const agent = useAgent({180 agent: "Counter",181 name: "my-instance",182 onStateUpdate: (newState) => setLocalState(newState),183 onIdentity: (name, agentType) => console.log(`Connected to ${name}`)184 });185186 return (187 <button onClick={() => agent.setState({ count: state.count + 1 })}>188 Count: {state.count}189 </button>190 );191}192```193194## References195196### Core197- **[references/state-scheduling.md](references/state-scheduling.md)** — State persistence, scheduling, SQL198- **[references/callable.md](references/callable.md)** — RPC methods, streaming, timeouts199- **[references/routing.md](references/routing.md)** — URL patterns, custom routing, `getAgentByName`200- **[references/configuration.md](references/configuration.md)** — Wrangler config, bindings, Vite setup201202### Chat & Streaming203- **[references/streaming-chat.md](references/streaming-chat.md)** — AIChatAgent, resumable streams, tools204- **[references/client-sdk.md](references/client-sdk.md)** — `useAgent`, `useAgentChat`, `AgentClient`205- **[references/server-driven-messages.md](references/server-driven-messages.md)** — Trigger patterns, `saveMessages`206- **[references/human-in-the-loop.md](references/human-in-the-loop.md)** — Approval flows, `needsApproval`207208### Background Processing209- **[references/workflows.md](references/workflows.md)** — Durable Workflows integration210- **[references/durable-execution.md](references/durable-execution.md)** — `runFiber`, `stash`, surviving eviction211- **[references/queue-retries.md](references/queue-retries.md)** — Built-in queue, retry with backoff212213### Integrations214- **[references/mcp.md](references/mcp.md)** — MCP client and server, transports, securing215- **[references/email.md](references/email.md)** — Email routing and handling216- **[references/webhooks-push.md](references/webhooks-push.md)** — Webhooks, push notifications217- **[references/observability.md](references/observability.md)** — Diagnostics-channel events218219### Experimental220- **[references/think.md](references/think.md)** — `@cloudflare/think` higher-level chat agent221- **[references/voice.md](references/voice.md)** — `@cloudflare/voice` STT/TTS222- **[references/codemode.md](references/codemode.md)** — Code Mode for tool orchestration223- **[references/browse-the-web.md](references/browse-the-web.md)** — CDP browser tools