Skip to content
Cloudflare Agents SDK

Cloudflare Agents SDK Skill

Build stateful AI agents on Cloudflare Workers — durable state, scheduling, RPC, WebSockets, and MCP servers.

GitHub Docs
Development
Added to Onei
Apache-2.0

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from cloudflare/skills.

$ npx skills add cloudflare/skills --skill agents-sdk

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/agents-sdk/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/cloudflare/skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/agents-sdk ~/.claude/skills/agents-sdk

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/agents-sdk/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Stateful agents with durable state and scheduling
  • Real-time WebSocket and streaming chat patterns
  • MCP server and browser-automation integration

Cloudflare's official skill for the Agents SDK, which turns Durable Objects into a runtime for long-lived AI agents.

It covers the patterns that make agents work at the edge: persisting state across requests without a database round trip, scheduling future work with alarms, streaming responses over WebSockets, exposing an agent as an MCP server, and calling out to browser automation and other Cloudflare services.

Particularly useful because agent frameworks change quickly and the SDK's idioms — how state is declared, how scheduling works, how a chat session is wired — are not something a model reliably knows. Published and maintained by Cloudflare.

SKILL.md

The instructions your agent loads, as published by Cloudflare.

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/

TopicDocs URLUse for
Getting startedQuick startFirst agent, project setup
Adding to existing projectAdd to existing projectInstall into existing Workers app
ConfigurationConfigurationwrangler.jsonc, bindings, assets, deployment
Agent classAgents APIAgent lifecycle, patterns, pitfalls
StateStore and sync statesetState, validateStateChange, persistence
RoutingRoutingURL patterns, routeAgentRequest
Callable methodsCallable methods@callable, RPC, streaming, timeouts
SchedulingSchedule tasksschedule(), scheduleEvery(), cron
WorkflowsRun workflowsAgentWorkflow, durable multi-step tasks
HTTP/WebSocketsWebSocketsLifecycle hooks, hibernation
Chat agentsChat agentsAIChatAgent, streaming, tools, persistence
Client SDKClient SDKuseAgent, useAgentChat, React hooks
Client toolsClient toolsClient-side tools, autoContinueAfterToolResult
Server-driven messagesTrigger patternssaveMessages, waitUntilStable, server-initiated turns
Resumable streamingResumable streamingStream recovery on disconnect
EmailEmailEmail routing, secure reply resolver
MCP clientMCP clientConnecting to MCP servers
MCP serverMCP serverBuilding MCP servers with McpAgent
MCP transportsMCP transportsStreamable HTTP, SSE, RPC transport options
Securing MCP serversSecuring MCPOAuth, proxy MCP, hardening
Human-in-the-loopHuman-in-the-loopApproval flows, needsApproval, workflows
Durable executionDurable executionrunFiber(), stash(), surviving DO eviction
QueueQueueBuilt-in FIFO queue, queue()
RetriesRetriesthis.retry(), backoff/jitter
ObservabilityObservabilityDiagnostics-channel events
Push notificationsPush notificationsWeb Push + VAPID from agents
WebhooksWebhooksReceiving external webhooks
Cross-domain authCross-domain authWebSocket auth, tokens, CORS
Readonly connectionsReadonlyshouldConnectionBeReadonly
VoiceVoiceExperimental STT/TTS, withVoice
Browse the webBrowser toolsExperimental CDP browser automation
ThinkThinkExperimental higher-level chat agent class
MigrationsAI SDK v5, AI SDK v6Upgrading @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}:

ClassURL
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
TaskAPI
Read statethis.state.count
Write statethis.setState({ count: 1 })
SQL query` this.sqlSELECT * 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 workflowawait this.runWorkflow("ProcessingWorkflow", params)
Durable fiberawait this.runFiber("name", async (ctx) => { ... })
Enqueue workthis.queue("handler", payload)
Retry with backoffawait this.retry(fn, { maxAttempts: 5 })
Broadcast to clientsthis.broadcast(message)
Get connectionsthis.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 onClick={() => agent.setState({ count: state.count + 1 })}>
      Count: {state.count}
    </button>
  );
}
References
Core
  • [references/state-scheduling.md](references/state-scheduling.md) — State persistence, scheduling, SQL
  • [references/callable.md](references/callable.md) — RPC methods, streaming, timeouts
  • [references/routing.md](references/routing.md) — URL patterns, custom routing, getAgentByName
  • [references/configuration.md](references/configuration.md) — Wrangler config, bindings, Vite setup
Chat & Streaming
  • [references/streaming-chat.md](references/streaming-chat.md) — AIChatAgent, resumable streams, tools
  • [references/client-sdk.md](references/client-sdk.md) — useAgent, useAgentChat, AgentClient
  • [references/server-driven-messages.md](references/server-driven-messages.md) — Trigger patterns, saveMessages
  • [references/human-in-the-loop.md](references/human-in-the-loop.md) — Approval flows, needsApproval
Background Processing
  • [references/workflows.md](references/workflows.md) — Durable Workflows integration
  • [references/durable-execution.md](references/durable-execution.md) — runFiber, stash, surviving eviction
  • [references/queue-retries.md](references/queue-retries.md) — Built-in queue, retry with backoff
Integrations
  • [references/mcp.md](references/mcp.md) — MCP client and server, transports, securing
  • [references/email.md](references/email.md) — Email routing and handling
  • [references/webhooks-push.md](references/webhooks-push.md) — Webhooks, push notifications
  • [references/observability.md](references/observability.md) — Diagnostics-channel events
Experimental
  • [references/think.md](references/think.md) — @cloudflare/think higher-level chat agent
  • [references/voice.md](references/voice.md) — @cloudflare/voice STT/TTS
  • [references/codemode.md](references/codemode.md) — Code Mode for tool orchestration
  • [references/browse-the-web.md](references/browse-the-web.md) — CDP browser tools
Install

Skill: Turnstile Spin

by Cloudflare

Turns “set up Turnstile” into a working end-to-end bot check — widget, frontend snippets, canonical server-side siteverify, and a real validation pass before it reports success.

Browse all skills →