AI Skills
agents-sdk

agents-sdk

熱門

使用 Agents SDK 在 Cloudflare Workers 上建構 AI 代理。當需要建立有狀態代理、持久化工作流程、即時 WebSocket 應用、排程任務、MCP 伺服器、聊天應用、語音代理或瀏覽器自動化時載入。涵蓋 Agent 類別、狀態管理、可呼叫 RPC、Workflows、持久化執行、佇列、重試、可觀測性及 React hooks。傾向從 Cloudflare 文件檢索而非依賴預訓練知識。

2012星標
180分支
更新於 2026/7/1
獲取技能源代碼

相關技能

azure-storage1196firebase-crashlytics357xiaohongshu112
SKILL.md
readonlyread-only
name
agents-sdk
description

使用 Agents SDK 在 Cloudflare Workers 上建構 AI 代理。當需要建立有狀態代理、持久化工作流程、即時 WebSocket 應用、排程任務、MCP 伺服器、聊天應用、語音代理或瀏覽器自動化時載入。涵蓋 Agent 類別、狀態管理、可呼叫 RPC、Workflows、持久化執行、佇列、重試、可觀測性及 React hooks。傾向從 Cloudflare 文件檢索而非依賴預訓練知識。

Cloudflare Agents SDK

你對 Agents SDK 的知識可能已過時。對於任何 Agents SDK 任務，優先檢索而非預訓練。

檢索來源

Cloudflare 文件：https://developers.cloudflare.com/agents/

主題 文件網址 用途
入門 快速開始 第一個代理、專案設定
加入現有專案 加入現有專案 安裝到現有 Workers 應用
設定 設定 wrangler.jsonc、綁定、靜態資源、部署
Agent 類別 Agents API Agent 生命週期、模式、陷阱
狀態 儲存與同步狀態 setState、validateStateChange、持久化
路由 路由 URL 模式、routeAgentRequest
可呼叫方法 可呼叫方法 @callable、RPC、串流、超時
排程 排程任務 schedule()、scheduleEvery()、cron
Workflows 執行 Workflows AgentWorkflow、持久化多步驟任務
HTTP/WebSockets WebSockets 生命週期鉤子、休眠
聊天代理 聊天代理 AIChatAgent、串流、工具、持久化
Client SDK Client SDK useAgent、useAgentChat、React hooks
客戶端工具 客戶端工具 客戶端工具、autoContinueAfterToolResult
伺服器驅動訊息 觸發模式 saveMessages、waitUntilStable、伺服器發起回合
可恢復串流 可恢復串流 斷線時串流恢復
電子郵件 電子郵件 電子郵件路由、安全回覆解析器
MCP 客戶端 MCP 客戶端 連接到 MCP 伺服器
MCP 伺服器 MCP 伺服器 使用 McpAgent 建構 MCP 伺服器
MCP 傳輸 MCP 傳輸 Streamable HTTP、SSE、RPC 傳輸選項
保護 MCP 伺服器 保護 MCP OAuth、代理 MCP、強化
人機迴圈 人機迴圈 核准流程、needsApproval、workflows
持久化執行 持久化執行 runFiber()、stash()、在 DO 驅逐後存活
佇列 佇列 內建 FIFO 佇列、queue()
重試 重試 this.retry()、退避/抖動
可觀測性 可觀測性 Diagnostics-channel 事件
推播通知 推播通知 來自代理的 Web Push + VAPID
Webhooks Webhooks 接收外部 webhooks
跨域認證 跨域認證 WebSocket 認證、令牌、CORS
唯讀連線 唯讀 shouldConnectionBeReadonly
語音 語音 實驗性 STT/TTS、withVoice
瀏覽網頁 瀏覽器工具 實驗性 CDP 瀏覽器自動化
思考 思考 實驗性高階聊天代理類別
遷移 AI SDK v5、AI SDK v6 升級 @cloudflare/ai-chat

功能

Agents SDK 提供：

  • 持久化狀態 — 基於 SQLite，透過 setState 自動同步至客戶端
  • 可呼叫 RPC — 透過 WebSocket 呼叫的 @callable() 方法
  • 排程 — 一次性、重複 (scheduleEvery) 及 cron 任務
  • Workflows — 透過 AgentWorkflow 進行持久化多步驟背景處理
  • 持久化執行 — runFiber() / stash() 用於在 DO 驅逐後仍存活的工作
  • 佇列 — 內建 FIFO 佇列，支援重試，透過 queue()
  • 重試 — this.retry() 搭配指數退避和抖動
  • MCP 整合 — 連接到 MCP 伺服器或使用 McpAgent 建構自己的伺服器
  • 電子郵件處理 — 接收並回覆電子郵件，具安全路由
  • 串流聊天 — AIChatAgent 搭配可恢復串流、訊息持久化、工具
  • 伺服器驅動訊息 — saveMessages、waitUntilStable 用於主動代理回合
  • React hooks — useAgent、useAgentChat 用於客戶端應用
  • 可觀測性 — diagnostics_channel 事件用於狀態、RPC、排程、生命週期
  • 推播通知 — 來自代理的 Web Push + VAPID 傳遞
  • Webhooks — 接收並驗證外部 webhooks
  • 語音（實驗性）— 透過 @cloudflare/voice 進行 STT/TTS
  • 瀏覽器工具（實驗性）— 透過 agents/browser 進行 CDP 驅動瀏覽
  • 思考（實驗性）— 透過 @cloudflare/think 的高階聊天代理

首先：驗證安裝

npm ls agents  # 應顯示 agents 套件

若未安裝：

npm install agents

對於聊天代理：

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

Wrangler 設定

{
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
}

注意事項：

  • 不要在 tsconfig 中啟用 experimentalDecorators（會破壞 @callable）
  • 絕不編輯舊的 migrations — 總是新增標籤
  • 每個代理類別需要自己的 DO 綁定 + migration 條目
  • 為 Workers AI 加入 "ai": { "binding": "AI" }

Agent 類別

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 })
};

路由

請求路由到 /agents/{agent-name}/{instance-name}：

類別 URL
Counter /agents/counter/user-123
ChatRoom /agents/chat-room/lobby

客戶端：useAgent({ agent: "Counter", name: "user-123" })

自訂路由：使用 getAgentByName(env.MyAgent, "instance-id") 然後 agent.fetch(request)。

核心 API

任務 API
讀取狀態 this.state.count
寫入狀態 this.setState({ count: 1 })
SQL 查詢 this.sql`SELECT * FROM users WHERE id = ${id}`
排程（延遲） await this.schedule(60, "task", payload)
排程（cron） await this.schedule("0 * * * *", "task", payload)
排程（間隔） await this.scheduleEvery(30, "poll")
RPC 方法 @callable() myMethod() { ... }
串流 RPC @callable({ streaming: true }) stream(res) { ... }
啟動 workflow await this.runWorkflow("ProcessingWorkflow", params)
持久化 fiber await this.runFiber("name", async (ctx) => { ... })
排入佇列 this.queue("handler", payload)
重試（退避） await this.retry(fn, { maxAttempts: 5 })
廣播給客戶端 this.broadcast(message)
取得連線 this.getConnections(tag?)

React 客戶端

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>
  );
}

參考資料

核心

聊天與串流

背景處理

整合

實驗性