agents-sdk
Build AI agents on Cloudflare Workers using the Agents SDK. Load when creating stateful agents, durable workflows, real-time WebSocket apps, scheduled tasks, MCP servers, chat applications, voice agents, or browser automation. Covers Agent class, state management, callable RPC, Workflows, durable execution, queues, retries, observability, and React hooks. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- agents-sdk
- description
- Build AI agents on Cloudflare Workers using the Agents SDK. Load when creating stateful agents, durable workflows, real-time WebSocket apps, scheduled tasks, MCP servers, chat applications, voice agents, or browser automation. Covers Agent class, state management, callable RPC, Workflows, durable execution, queues, retries, observability, and React hooks. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
02 资源文件 19
- 参考文档references/browse-the-web.md1.6 KB
- 参考文档references/callable.md2.1 KB
- 参考文档references/client-sdk.md2.2 KB
- 参考文档references/codemode.md2.8 KB
- 参考文档references/configuration.md1.8 KB
- 参考文档references/durable-execution.md1.7 KB
- 参考文档references/email.md3.5 KB
- 参考文档references/human-in-the-loop.md1.8 KB
- 参考文档references/mcp.md4.6 KB
- 参考文档references/observability.md1.3 KB
- 参考文档references/queue-retries.md2.2 KB
- 参考文档references/routing.md1.8 KB
- 参考文档references/server-driven-messages.md1.6 KB
- 参考文档references/state-scheduling.md4.0 KB
- 参考文档references/streaming-chat.md5.0 KB
- 参考文档references/think.md2.9 KB
- 参考文档references/voice.md1.9 KB
- 参考文档references/webhooks-push.md2.4 KB
- 参考文档references/workflows.md3.8 KB
03 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 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 —
AIChatAgentwith resumable streams, message persistence, tools - Server-driven messages —
saveMessages,waitUntilStablefor proactive agent turns - React hooks —
useAgent,useAgentChatfor client apps - Observability —
diagnostics_channelevents 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
experimentalDecoratorsin 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/thinkhigher-level chat agent - references/voice.md —
@cloudflare/voiceSTT/TTS - references/codemode.md — Code Mode for tool orchestration
- references/browse-the-web.md — CDP browser tools
04 同仓库更多 Skills
seedance-prompt-en
Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.
onepage-pdf
Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.
native-feel-cross-platform-desktop
Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.
gstack
Router for the gstack skill suite. (gstack)
fireworks-tech-graph
Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated.
dbs-video-extract
接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。