Cloudflare Agents SDK
Builds and reviews apps on Cloudflare's Agents SDK: stateful agents on Durable Objects, callable RPC, scheduling, queues, Workflows, AIChatAgent chat, MCP and email. Use when building an AI agent or chat app on Workers.
agents-sdk- Author
- Cloudflare
- Source
- cloudflare/skills/skills/agents-sdk @ 5108325
- License
- Apache-2.0
About this skill
What it does
The skill helps the agent build, debug and review apps on Cloudflare's Agents SDK, the agents npm package, where each agent class is a Durable Object with its own SQLite storage. It starts by checking npm ls agents (chat apps also need @cloudflare/ai-chat, ai and @ai-sdk/react) and gives the config every agent class needs: a Durable Object binding, a new_sqlite_classes migration and nodejs_compat. Among its gotchas: experimentalDecorators in tsconfig breaks @callable, and old migrations are never edited.
SKILL.md shows a minimal agent with setState, validateStateChange and a @callable() method, routing to /agents/{kebab-class}/{instance} through routeAgentRequest, and core APIs: this.sql, schedule() with a delay or cron, scheduleEvery(), runWorkflow(), runFiber(), queue(), retry(), broadcast(). A table of 33 topics with docs links covers the rest.
Nineteen references split the topics. Some are short code guides: streaming callable methods, routing options, configuration with the Vite plugin, durable fibers (stash replaces the checkpoint, nothing retries on throw), email with HMAC-signed reply routing, webhooks and Web Push with VAPID keys, diagnostics_channel events. Others route to docs with a few design checks: state versus SQL, the built-in queue (no dead-letter queue), Workflows, approvals, MCP (createMcpHandler over the deprecated McpAgent). Four cover experimental features: @cloudflare/think (needs the experimental compatibility flag), @cloudflare/voice, Code Mode and CDP browser tools, the last two on a worker_loaders binding. skill-feedback.md drafts an issue for cloudflare/skills that you approve first.
When to use it, and when not
Use it for stateful AI agents, chat apps with streaming and tools, scheduled or long-running agent work, and MCP servers or clients on Workers.
For a plain Durable Object without agent features, the Durable Objects skill fits better. Many references are mostly links, so the agent needs web access.
How to run it
The install command below puts SKILL.md, the references and the licence in place. To call the skill yourself:
- Claude Code:
/agents-sdk, or ask for the skill by name. - Codex:
$agents-sdk. - Cursor: type
/in the Agent chat and pickagents-sdk.
Example: /agents-sdk Build a support chat agent on AIChatAgent that schedules a callback and asks for approval before a refund.
How it differs from similar skills
Cloudflare Durable Objects is the layer underneath, for objects you write by hand. MCP server builder builds a plain MCP server for an external API and adds an evaluation run; here MCP is one feature of an agent on Workers. ChatGPT Apps SDK also centres on an MCP server, but for an app with a widget inside ChatGPT.
Install
Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.
curl -fsSL --create-dirs -o ~/.claude/skills/agents-sdk/SKILL.md https://anymodel.org/en/skills/cloudflare/agents-sdk/SKILL.md -o ~/.claude/skills/agents-sdk/LICENSE https://anymodel.org/en/skills/cloudflare/agents-sdk/LICENSE -o ~/.claude/skills/agents-sdk/references/browse-the-web.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/browse-the-web.md -o ~/.claude/skills/agents-sdk/references/callable.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/callable.md -o ~/.claude/skills/agents-sdk/references/client-sdk.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/client-sdk.md -o ~/.claude/skills/agents-sdk/references/codemode.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/codemode.md -o ~/.claude/skills/agents-sdk/references/configuration.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/configuration.md -o ~/.claude/skills/agents-sdk/references/durable-execution.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/durable-execution.md -o ~/.claude/skills/agents-sdk/references/email.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/email.md -o ~/.claude/skills/agents-sdk/references/human-in-the-loop.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/human-in-the-loop.md -o ~/.claude/skills/agents-sdk/references/mcp.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/mcp.md -o ~/.claude/skills/agents-sdk/references/observability.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/observability.md -o ~/.claude/skills/agents-sdk/references/queue-retries.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/queue-retries.md -o ~/.claude/skills/agents-sdk/references/routing.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/routing.md -o ~/.claude/skills/agents-sdk/references/server-driven-messages.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/server-driven-messages.md -o ~/.claude/skills/agents-sdk/references/skill-feedback.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/skill-feedback.md -o ~/.claude/skills/agents-sdk/references/state-scheduling.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/state-scheduling.md -o ~/.claude/skills/agents-sdk/references/streaming-chat.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/streaming-chat.md -o ~/.claude/skills/agents-sdk/references/think.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/think.md -o ~/.claude/skills/agents-sdk/references/voice.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/voice.md -o ~/.claude/skills/agents-sdk/references/webhooks-push.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/webhooks-push.md -o ~/.claude/skills/agents-sdk/references/workflows.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/workflows.md
curl -fsSL --create-dirs -o ~/.agents/skills/agents-sdk/SKILL.md https://anymodel.org/en/skills/cloudflare/agents-sdk/SKILL.md -o ~/.agents/skills/agents-sdk/LICENSE https://anymodel.org/en/skills/cloudflare/agents-sdk/LICENSE -o ~/.agents/skills/agents-sdk/references/browse-the-web.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/browse-the-web.md -o ~/.agents/skills/agents-sdk/references/callable.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/callable.md -o ~/.agents/skills/agents-sdk/references/client-sdk.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/client-sdk.md -o ~/.agents/skills/agents-sdk/references/codemode.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/codemode.md -o ~/.agents/skills/agents-sdk/references/configuration.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/configuration.md -o ~/.agents/skills/agents-sdk/references/durable-execution.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/durable-execution.md -o ~/.agents/skills/agents-sdk/references/email.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/email.md -o ~/.agents/skills/agents-sdk/references/human-in-the-loop.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/human-in-the-loop.md -o ~/.agents/skills/agents-sdk/references/mcp.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/mcp.md -o ~/.agents/skills/agents-sdk/references/observability.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/observability.md -o ~/.agents/skills/agents-sdk/references/queue-retries.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/queue-retries.md -o ~/.agents/skills/agents-sdk/references/routing.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/routing.md -o ~/.agents/skills/agents-sdk/references/server-driven-messages.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/server-driven-messages.md -o ~/.agents/skills/agents-sdk/references/skill-feedback.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/skill-feedback.md -o ~/.agents/skills/agents-sdk/references/state-scheduling.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/state-scheduling.md -o ~/.agents/skills/agents-sdk/references/streaming-chat.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/streaming-chat.md -o ~/.agents/skills/agents-sdk/references/think.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/think.md -o ~/.agents/skills/agents-sdk/references/voice.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/voice.md -o ~/.agents/skills/agents-sdk/references/webhooks-push.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/webhooks-push.md -o ~/.agents/skills/agents-sdk/references/workflows.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/workflows.md
foreach ($f in 'SKILL.md','LICENSE','references/browse-the-web.md','references/callable.md','references/client-sdk.md','references/codemode.md','references/configuration.md','references/durable-execution.md','references/email.md','references/human-in-the-loop.md','references/mcp.md','references/observability.md','references/queue-retries.md','references/routing.md','references/server-driven-messages.md','references/skill-feedback.md','references/state-scheduling.md','references/streaming-chat.md','references/think.md','references/voice.md','references/webhooks-push.md','references/workflows.md') { $p = Join-Path "$HOME\.claude\skills\agents-sdk" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/cloudflare/agents-sdk/$f" -UseBasicParsing -OutFile $p }foreach ($f in 'SKILL.md','LICENSE','references/browse-the-web.md','references/callable.md','references/client-sdk.md','references/codemode.md','references/configuration.md','references/durable-execution.md','references/email.md','references/human-in-the-loop.md','references/mcp.md','references/observability.md','references/queue-retries.md','references/routing.md','references/server-driven-messages.md','references/skill-feedback.md','references/state-scheduling.md','references/streaming-chat.md','references/think.md','references/voice.md','references/webhooks-push.md','references/workflows.md') { $p = Join-Path "$HOME\.agents\skills\agents-sdk" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/cloudflare/agents-sdk/$f" -UseBasicParsing -OutFile $p }Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/cloudflare/agents-sdk/SKILL.md
SKILL.md
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/index.md
| 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, AgentClient, state, RPC, HTTP |
| Client tools | Client tools | Client-side tools, autoContinueAfterToolResult |
| Server-driven messages | Autonomous responses | saveMessages, waitUntilStable, server-initiated turns |
| Resumable streaming | Chat agents | Stream recovery on disconnect |
| Email routing, secure reply resolver | ||
| MCP client | MCP client | Connecting to MCP servers |
| MCP server | MCP server | Building MCP servers with createMcpHandler |
| 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 | Workflow approvals, elicitation, timeout handling |
| 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
createMcpHandler - Email handling — Receive and reply to emails with secure routing
- Streaming chat —
AIChatAgentwith resumable streams, message persistence, tools - Server-driven messages —
saveMessages,waitUntilStablefor proactive agent turns - React hooks —
useAgent,useAgentChatfor client apps - Observability —
diagnostics_channelevents 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
experimentalDecoratorsin 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
Read client-sdk.md for client selection and current connection examples. For chat UI and tools, also read streaming-chat.md.
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/thinkhigher-level chat agent - references/voice.md —
@cloudflare/voiceSTT/TTS - references/codemode.md — Code Mode for tool orchestration
- references/browse-the-web.md — CDP browser tools
Skill feedback
If the user reports that this skill gave incorrect or outdated guidance, or is missing information, read references/skill-feedback.md.
Connect through AnyModel API
This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.
AnyModel