Setting the skill. One moment.
Skills
Skill 1 of 14
Build, debug, or review Cloudflare Agents SDK applications using the agents package.
2 minutes · 526 words · 15 sections
Install
npx skills add cloudflare/skills --skill agents-sdknpx skills add cloudflare/skills/plugin marketplace add cloudflare/skillsThe first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.
Your knowledge of the Agents SDK may be outdated. Prefer retrieval over pre-training for any Agents SDK task.
Cloudflare docs: https://developers.cloudflare.com/agents/ (opens in a new tab)
| Topic | Docs URL | Use for |
|---|---|---|
| Getting started | Quick start (opens in a new tab) | First agent, project setup |
| Adding to existing project | Add to existing project (opens in a new tab) | Install into existing Workers app |
| Configuration | Configuration (opens in a new tab) | wrangler.jsonc, bindings, assets, deployment |
| Agent class | Agents API (opens in a new tab) | Agent lifecycle, patterns, pitfalls |
| State | Store and sync state (opens in a new tab) | setState, validateStateChange, persistence |
| Routing | Routing (opens in a new tab) | URL patterns, routeAgentRequest |
| Callable methods | Callable methods (opens in a new tab) | @callable, RPC, streaming, timeouts |
| Scheduling | Schedule tasks (opens in a new tab) | schedule(), scheduleEvery(), cron |
| Workflows | Run workflows (opens in a new tab) | AgentWorkflow, durable multi-step tasks |
| HTTP/WebSockets | WebSockets (opens in a new tab) | Lifecycle hooks, hibernation |
| Chat agents | Chat agents (opens in a new tab) | AIChatAgent, streaming, tools, persistence |
| Client SDK | Client SDK (opens in a new tab) | useAgent, AgentClient, state, RPC, HTTP |
| Client tools | Client tools (opens in a new tab) | Client-side tools, autoContinueAfterToolResult |
| Server-driven messages | Autonomous responses (opens in a new tab) | saveMessages, waitUntilStable, server-initiated turns |
| Resumable streaming | Chat agents (opens in a new tab) | Stream recovery on disconnect |
| Email (opens in a new tab) | Email routing, secure reply resolver | |
| MCP client | MCP client (opens in a new tab) | Connecting to MCP servers |
| MCP server | MCP server (opens in a new tab) | Building MCP servers with createMcpHandler |
| MCP transports | MCP transports (opens in a new tab) | Streamable HTTP, SSE, RPC transport options |
| Securing MCP servers | Securing MCP (opens in a new tab) | OAuth, proxy MCP, hardening |
| Human-in-the-loop | Human-in-the-loop (opens in a new tab) | Workflow approvals, elicitation, timeout handling |
| Durable execution | Durable execution (opens in a new tab) | runFiber(), stash(), surviving DO eviction |
| Queue | Queue (opens in a new tab) | Built-in FIFO queue, queue() |
| Retries | Retries (opens in a new tab) | this.retry(), backoff/jitter |
| Observability | Observability (opens in a new tab) | Diagnostics-channel events |
| Push notifications | Push notifications (opens in a new tab) | Web Push + VAPID from agents |
| Webhooks | Webhooks (opens in a new tab) | Receiving external webhooks |
| Cross-domain auth | Cross-domain auth (opens in a new tab) | WebSocket auth, tokens, CORS |
| Readonly connections | Readonly (opens in a new tab) | shouldConnectionBeReadonly |
| Voice | Voice (opens in a new tab) | Experimental STT/TTS, withVoice |
| Browse the web | Browser tools (opens in a new tab) | Experimental CDP browser automation |
| Think | Think (opens in a new tab) | Experimental higher-level chat agent class |
| Migrations | AI SDK v5 (opens in a new tab), AI SDK v6 (opens in a new tab) | Upgrading @cloudflare/ai-chat |
The Agents SDK provides:
setState@callable() methods invoked over WebSocketscheduleEvery), and cron tasksAgentWorkflowrunFiber() / stash() for work that survives DO evictionqueue()this.retry() with exponential backoff and jittercreateMcpHandlerAIChatAgent with resumable streams, message persistence, toolssaveMessages, waitUntilStable for proactive agent turnsuseAgent, useAgentChat for client appsdiagnostics_channel events for state, RPC, schedule, lifecycle@cloudflare/voiceagents/browser@cloudflare/thinknpm ls agents # Should show agents packageIf not installed:
npm install agentsFor chat agents:
npm install agents @cloudflare/ai-chat ai @ai-sdk/react{
"compatibility_flags": ["nodejs_compat"],
"durable_objects": {
"bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
},
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
}Gotchas:
experimentalDecorators in tsconfig (breaks @callable)"ai": { "binding": "AI" } for Workers AIimport { 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 })
};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).
| 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?) |
Read client-sdk.md (opens in a new tab) for client selection and current connection examples. For chat UI and tools, also read streaming-chat.md (opens in a new tab).
getAgentByNameuseAgent, useAgentChat, AgentClientsaveMessagesneedsApprovalrunFiber, stash, surviving eviction@cloudflare/think higher-level chat agent@cloudflare/voice STT/TTSmain, last pushed 22 September 2026.SKILL.md, not by matching a directory convention. One layout observed: skills/*/SKILL.md.h1 and no skipped levels:.claude-plugin/marketplace.json by Cloudflare, declaring 1 plugin. It is read for editorial metadata only — never as the skill index, which is always the repository tree./cloudflare/skills.md, and each skill at its own .md URL.19 files · 34 KB
Everything this skill ships beside its prose. All of it is set here, as subchapters of skill 1.
Documentation the agent loads on demand, rather than up front.