AGENT SKILL

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

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

Chat & Streaming

Background Processing

Integrations

Experimental

04 同仓库更多 Skills

shengdabai
shengdabai/Tony-Claude-Code-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.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

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.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

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.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

gstack

Router for the gstack skill suite. (gstack)

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

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.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

dbs-video-extract

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

★ 3