cloudflare/agents

Cloudflare Agents – 狀態保持型、伺服器端 AI/工具代理

是什麼 – 一個 TypeScript/JavaScript SDK，讓你能在 Cloudflare Workers 上撰寫 Durable Objects，並將每個物件視為獨立、長期運行的「代理」。代理擁有自己的持久化儲存空間，可執行排程工作、維持 WebSocket 連線、呼叫 AI 模型、作為 MCP（多通道協定）伺服器或用戶端，並透過 @callable() 裝飾器公開類型安全的 RPC 方法。執行時會自動將閒置代理休眠，並在需要時喚醒，因此你可以以近乎零的閒置成本，啟動數百萬個使用者或會話級代理。

核心概念

概念	提供的功能
持久狀態	狀態儲存在 Cloudflare Durable Object 中，重啟後仍保留；變更會自動同步至所有連接的客戶端。
可呼叫方法	使用 `@callable()` 裝飾類方法 – 它們會變成類型安全的 RPC 端點，可從瀏覽器或其他 Workers 呼叫。
子代理	代理可透過特徵（facets）和巢狀路由組合其他代理（父/子），實現階層式工作負載。
排程	可在代理內安排一次性、重複性或 cron 風格的任務。
WebSocket	內建即時雙向通道，支援生命週期鈎子。
AI 聊天與工具	內建聊天層（`@cloudflare/ai-chat`），支援訊息持久化、可恢復串流，並可將子代理作為「工具」執行。
MCP / WebMCP	代理可公開或消費多通道協定（HTTP、SSE、RPC 等），並橋接這些工具與瀏覽器。
工作流程	支援暫停/恢復與審核步驟的多階段、人機協作流程。
郵件與語音	直接整合 Cloudflare 郵件服務與語音管道（STT/TTS、VAD、SFU）。
程式碼模式	LLM 可產生呼叫你工具的 TypeScript 程式碼，產生的程式碼在沙箱 Worker（`@cloudflare/shell`）中執行。
支付（x402）	可透過 x402 協定對按呼叫計費的 API 進行計費。
可觀測性	自動發出追蹤、指標與結構化日誌。
SQL	代理可直接在 Durable Object 內執行 SQLite 查詢。
前端鈎子	提供 React 鈎子（`useAgent`、`useAgentChat`、`useVoiceAgent`）與原生 JS 客戶端（`AgentClient`），方便整合。

單體儲存庫中的套件

套件	作用
`agents`	核心 SDK – 代理、路由、排程、MCP、工作流程、語音、瀏覽器代理等
`@cloudflare/ai-chat`	高階聊天抽象，支援持久訊息與工具執行
`@cloudflare/think`	帶有「代理迴圈」與工作區工具的有觀點聊天代理基底
`@cloudflare/codemode`	將 LLM 輸出轉換為可執行 TypeScript，呼叫你的工具
`@cloudflare/shell`	帶虛擬檔案系統的沙箱 JS 執行環境，用於安全的程式碼模式執行
`@cloudflare/voice`	語音 API 相容包裝器（已棄用，建議使用核心 `agents/voice` 導出）
`@cloudflare/worker-bundler`	運行時打包 Workers，與 Worker-Loader 綁定一起使用
`hono-agents`	為 Hono Web 框架應用新增代理的中間件

典型用例

使用者級助理 – 每位使用者一個代理，儲存對話歷程、偏好，並執行排程提醒。
即時多人房間 – 每個遊戲房間是一個代理，透過 WebSocket 同步狀態給所有玩家。
工具呼叫 AI 助理 – LLM 呼叫子代理（如日曆代理、搜尋代理），並將結果串流回使用者。
工作流程自動化 – 複雜多階段流程（如工單分類 → 人工審核 → 執行）可建模為持久工作流程。
語音機器人 – 結合 STT/TTS 服務與代理，維持對話狀態並呼叫其他工具。
按呼叫計費 API – 將函數公開為 x402 計費端點；代理處理計費與限流。

快速開始（來自 README）

建立啟動專案

npm create cloudflare@latest -- --template cloudflare/agents-starter

或向現有 Worker 新增 SDK
```
npm install agents
```
撰寫代理 – 繼承 Agent 並使用 @callable() 標記方法（參見 README 中的計數器範例）。
在 wrangler.jsonc 中設定 Durable Objects（繫結名稱、類別名稱、SQLite 迁移標籤）。
使用 Cloudflare Wrangler 部署，如同部署一般 Worker 一樣。
從瀏覽器消費 – 使用 React 鈎子 useAgent（或原生 AgentClient）呼叫方法並接收即時狀態更新。

文件與學習資源

完整文件 – https://developers.cloudflare.com/agents/（入門指南、API 參考、教學）。
範例 – examples/ 目錄下有 30+ 個自包含的示範（遊樂場、聊天助理、MCP 伺服器/用戶端、程式碼模式、語音管道、工作流程等）。
設計文件 – design/ 包含架構決策記錄與模式指南（Anthropic 模式、人機協作等）。
OpenAI SDK 範例 – openai-sdk/ 展示如何使用 OpenAI Agents JavaScript SDK 與 Cloudflare 代理整合。

開發工作流程（貢獻者）

Node 24+，pnpm 工作區，Nx 用於任務編排。
建構：pnpm run build（Nx 按依賴順序建構套件，快取結果）。
檢查：pnpm run check（lint + 類型檢查）。
測試：pnpm run test（Vitest + Workers 執行時）與 pnpm run test:react（Playwright React 鈎子測試）。
套件變更需提交 changeset（pnpm exec changeset）。
外部 PR 目前不接受；團隊偏好內部迭代，但歡迎提交 Issue 與討論。

授權

MIT – 寬鬆的開源授權。

總結 – Cloudflare Agents 是一個生產級框架，用於建構可在 Cloudflare 邊緣網路上大規模執行的狀態保持型、伺服器端 AI 代理，原生支援即時同步、排程、工具呼叫、語音、郵件、支付等功能。