Skip to content

fcakyon/claude-codex-settings / plugins/cloudflare-skills/skills/agents-sdk

agents-sdk

Unverified

Build, debug, or review Cloudflare Agents SDK applications using the agents package.

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

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, AgentClient, state, RPC, HTTP
Client toolsClient toolsClient-side tools, autoContinueAfterToolResult
Server-driven messagesAutonomous responsessaveMessages, waitUntilStable, server-initiated turns
Resumable streamingChat agentsStream recovery on disconnect
EmailEmailEmail routing, secure reply resolver
MCP clientMCP clientConnecting to MCP servers
MCP serverMCP serverBuilding MCP servers with createMcpHandler
MCP transportsMCP transportsStreamable HTTP, SSE, RPC transport options
Securing MCP serversSecuring MCPOAuth, proxy MCP, hardening
Human-in-the-loopHuman-in-the-loopWorkflow approvals, elicitation, timeout handling
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 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}:

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

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.

skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
webapp-testinganthropics/skillsToolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
browser-testing-with-devtoolsaddyosmani/agent-skillsTests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
ci-cd-and-automationaddyosmani/agent-skillsAutomates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies.Stars: 118kUpdated Claude CodeCodexVerifiedInstall