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.

AI models & APIsPack: Cloudflare skills206 linesagents-sdk
Author
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 pick agents-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.

Claude Code — macOS, Linux
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
Codex, Cursor — macOS, Linux
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
Claude Code — Windows PowerShell
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 }
Codex, Cursor — Windows PowerShell
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

Raw

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 Email 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 — 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

Read client-sdk.md for client selection and current connection examples. For chat UI and tools, also read streaming-chat.md.

References

Core

Chat & Streaming

Background Processing

Integrations

Experimental

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.

More from the pack Cloudflare skills

Cloudflare Workers best practices

Checks Cloudflare Workers code and config against production rules: current compatibility dates, logs and traces, streaming, waitUntil, bindings over REST calls, Web Crypto, generated Env types. Use when writing, reviewing or shipping a Worker.

Wrangler CLI

Guides Wrangler commands and config in projects with wrangler.jsonc or wrangler.toml, checking installed help and current docs and guarding secrets, environments and Previews. Use when deploying, configuring or debugging a Worker with Wrangler.

Cloudflare Durable Objects

Builds and reviews Cloudflare Durable Objects: one object per entity, SQLite storage and migrations, RPC methods, alarms, WebSockets and Vitest tests, with links to current docs. Use when a Workers app needs shared state or coordination.

Web frameworks on Cloudflare Workers

Sets up Astro, SvelteKit, React Router, TanStack Start, Nuxt, Hono and SPA apps on Cloudflare Workers, choosing C3, Wrangler or cf by the project's state. Use when creating, migrating or deploying a framework app on Workers.

Local Workers development

Runs and debugs Workers locally with cf dev, wrangler dev or the Vite plugin, using Local Explorer to read and seed binding data and query traces. Use when a local request fails or you need to see what a binding returned.

Cloudflare cf CLI

Finds and runs commands of Cloudflare's beta cf CLI through cf cli search, cf schema and dry runs, and picks cf or Wrangler per project. Use when managing DNS, zones, D1, KV or R2 from the terminal or starting a new Workers project.

Web performance audit

Audits a web page's loading performance through Chrome DevTools MCP: a trace, Core Web Vitals against thresholds, network, an accessibility snapshot and bundle config, with ranked fixes. Use when a page is slow or its Lighthouse score is low.