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 forGetting startedQuick startFirst agent, project setupAdding to existing projectAdd to existing projectInstall into existing Workers appConfigurationConfigurationwrangler.jsonc, bindings, assets, deploymentAgent classAgents APIAgent lifecycle, patterns, pitfallsStateStore and sync statesetState, validateStateChange, persistenceRoutingRoutingURL patterns, routeAgentRequestCallable methodsCallable methods@callable, RPC, streaming, timeoutsSchedulingSchedule tasksschedule(), scheduleEvery(), cronWorkflowsRun workflowsAgentWorkflow, durable multi-step tasksHTTP/WebSocketsWebSocketsLifecycle hooks, hibernationChat agentsChat agentsAIChatAgent, streaming, tools, persistenceClient SDKClient SDKuseAgent, useAgentChat, React hooksClient toolsClient toolsClient-side tools, autoContinueAfterToolResultServer-driven messagesTrigger patternssaveMessages, waitUntilStable, server-initiated turnsResumable streamingResumable streamingStream recovery on disconnectEmailEmailEmail routing, secure reply resolverMCP clientMCP clientConnecting to MCP serversMCP serverMCP serverBuilding MCP servers with McpAgentMCP transportsMCP transportsStreamable HTTP, SSE, RPC transport optionsSecuring MCP serversSecuring MCPOAuth, proxy MCP, hardeningHuman-in-the-loopHuman-in-the-loopApproval flows, needsApproval, workflowsDurable executionDurable executionrunFiber(), stash(), surviving DO evictionQueueQueueBuilt-in FIFO queue, queue()RetriesRetriesthis.retry(), backoff/jitterObservabilityObservabilityDiagnostics-channel eventsPush notificationsPush notificationsWeb Push + VAPID from agentsWebhooksWebhooksReceiving external webhooksCross-domain authCross-domain authWebSocket auth, tokens, CORSReadonly connectionsReadonlyshouldConnectionBeReadonlyVoiceVoiceExperimental STT/TTS, withVoiceBrowse the webBrowser toolsExperimental CDP browser automationThinkThinkExperimental higher-level chat agent classMigrationsAI 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#

bash

npm ls agents  # Should show agents package

If not installed:

bash

npm install agents

For chat agents:

bash

npm install agents @cloudflare/ai-chat ai @ai-sdk/react

Wrangler Configuration#

jsonc

{
  "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#

typescript

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}:

ClassURLCounter``/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#

TaskAPIRead statethis.state.countWrite statethis.setState({ count: 1 })SQL querythis.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 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#

tsx

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