agents-sdk

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/

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 onClick={() => 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