Index of every page on this site: llms.txt
All skills
cloudflare avatar

/agents-sdk

@5108325 official
by cloudflarecloudflare/skills3.4k stars
357
Run it yourself

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

  • 21 files
  • 49.4 KB
  • Updated 4 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/cloudflare/skills/agents-sdk

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈24 tokens for metadata: the name and description. ≈3k when used: this file. ≈9.6k more on demand in 20 files.

Description uses 1.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈97 characters, or 1.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 5108325. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 4 weeks ago
  • MCP
  • cloudflare
  • workers
  • agents
  • state-management
  • websocket
  • durable-objects
  • scheduling
  • workflows
  • observable

README badge

README badge for cloudflare/skills/agents-sdk

Builds stateful AI agents on Cloudflare Workers using Durable Objects, with APIs for persistent state, callable RPC methods, scheduling, workflows, durable execution, queues, and streaming chat. Covers the full lifecycle of agent development from configuration through observability, with experimental support for voice, browser automation, and MCP integration.

Generated from the current SKILL.md.

Does this work with existing Cloudflare Workers projects?
Yes. Use the 'Add to existing project' guide to install the SDK into an existing Workers app. You'll need to configure durable objects and migrations in wrangler.jsonc.
What state management does the SDK provide?
SQLite-backed persistent state that auto-syncs to clients via setState(). State changes trigger validateStateChange() and onStateUpdate() hooks, and the SDK includes built-in SQL query support.
Can I use this with chat applications?
Yes. The SDK includes AIChatAgent for streaming chat with tools, message persistence, and resumable streams. It requires @cloudflare/ai-chat and ai packages.
Does this support background workflows and scheduled tasks?
Yes. The SDK provides AgentWorkflow for durable multi-step tasks, schedule() / scheduleEvery() for one-time and recurring tasks, and runFiber() for work that survives durable object eviction.
Can I connect to external MCP servers or build MCP servers with this?
Yes. The SDK includes MCP client integration to connect to external MCP servers and McpAgent to build MCP servers with configurable transports (HTTP, SSE, RPC).

Generated from the current SKILL.md. These answers refresh after source changes.