agents-sdk

agents-sdk 技能總覽

agents-sdk 是用來做什麼的

agents-sdk 技能可協助你使用 Agents SDK 建立以 Cloudflare Workers 為基礎的 agents，特別適合需要有狀態對話、可持久執行、WebSocket 或即時互動、排程工作、MCP 整合，或瀏覽器驅動自動化的情境。對想快速判斷是否值得安裝的人來說，agents-sdk skill 最有價值的地方在於它回答的是實作前的關鍵問題：這個 SDK 能不能勝任、需要哪些設定，以及正式寫程式前應該先讀什麼。

最適合的使用情境

當你要建立生產環境中的 Worker，而且需要持久化 agent 狀態、可呼叫方法、型別化的客戶端存取、以 queue 為基礎的工作流程、重試、可觀測性，或 React client hooks 時，最適合使用 agents-sdk。若是 agents-sdk for Multi-Agent Systems，只有在這些 agents 都跑在 Cloudflare 的執行環境內，並且共用 Worker/Durable Object 的限制時，才算是很合適的選擇。

它有什麼不同

這個技能不是一個泛用的「幫我做個 agent」提示。它綁定的是 Cloudflare 的實作細節：Durable Objects、wrangler.jsonc、migrations、nodejs_compat，以及像 @callable()、runFiber、useAgent 這類 API 專屬模式。也就是說，真正的導入風險主要在設定，不在概念設計。

如何使用 agents-sdk 技能

安裝並確認情境正確

先透過 skills manager 執行 agents-sdk install，再確認你是在 Cloudflare Workers 的 repo 裡工作，而不是獨立的聊天應用。標準安裝方式如下：

npx skills add cloudflare/skills --skill agents-sdk

安裝完成後，請先從 SKILL.md 開始，再優先查看 references/configuration.md、references/client-sdk.md、references/callable.md 和 references/durable-execution.md。這些檔案會直接回答最常卡住導入的幾個問題：bindings、migrations、客戶端連線，以及狀態如何在重啟後延續。

把粗略目標改寫成有用的提示詞

這個技能在提示詞明確描述執行環境，而不只是功能本身時，效果會更好。好的輸入應包含：

• agent 類型：chat agent、workflow agent、voice agent、browser agent，或 MCP server
• 是新專案，還是加進既有的 Workers app
• 客戶端介面：React hook、純 JavaScript client、RPC、email，或 WebSocket
• 持久化需求：簡單狀態、durable execution，或 queue / retry 流程

更強的 agents-sdk usage 請求範例如下：
“新增一個 Cloudflare Worker agent，為每位使用者儲存各自狀態，提供一個 callable method，並透過 React client 串流聊天回應。請使用目前的 Agents SDK 設定規則，並說明需要哪些 wrangler.jsonc 變更。”

依正確順序閱讀 repo

對大多數安裝情境來說，最有價值的閱讀順序是：

1. SKILL.md：支援的模式與檢索來源
2. references/configuration.md：bindings、migrations 與本機開發設定
3. references/callable.md 和 references/client-sdk.md：客戶端與伺服器互動
4. 如果應用需要持久化或長時間執行，先看 references/state-scheduling.md、references/workflows.md，或 references/durable-execution.md
5. 如果你很在意可靠性，再看 references/observability.md 和 references/queue-retries.md

會直接影響輸出品質的實用技巧

請把你現有的 wrangler.jsonc、目前的 agent class 名稱，以及新程式碼應該放在哪個精確路徑一併提供。也請說明你是否已經在使用 React、Workers AI 或 MCP。另外，請明確指出你要的是最小可運作範例，還是整合式修補，因為這兩種目標下，SDK 的設定細節差異很大。

agents-sdk 技能 FAQ

agents-sdk 只適合新專案嗎？

不是。agents-sdk guide 同時支援新建的 Workers app 與既有專案，但既有 repo 需要更仔細檢查設定。如果你已經有 bindings、migrations，或自訂的建置堆疊，最好一開始就把這些細節提供出來，這樣技能才能順利貼合現有架構。

我需要先懂 Cloudflare 嗎？

有基本的 Cloudflare 基礎知識會更順手，但只要你能照著設定指示操作並讀懂 wrangler.jsonc，這個技能就很實用。初學者通常只要先鎖定一個明確目標，例如先做出單一 agent 搭配單一路徑的 client，就能運作得不錯；一開始就要做完整的 multi-agent system，反而容易失焦。

什麼情況下不該用 agents-sdk？

如果你只需要無狀態的 API wrapper、單次 LLM 呼叫，或是完全不依賴 Cloudflare runtime 的供應商中立聊天機器人，就不要用 agents-sdk。如果你無法使用 Durable Objects、Workers 的限制，或 Cloudflare 專屬的部署流程，這個技能也不太適合。

這和一般提示詞有什麼不同？

一般提示詞可能只是在概念上描述一個 agent，但 agents-sdk 是建立在 Cloudflare 真正的 API 表面與部署規則之上。這能減少對 @callable()、state、migrations 和 client hooks 的猜測，而這些地方正是泛用指引最常失準的區域。

如何改進 agents-sdk 技能

明確說出部署形態

影響品質最大的提升，來自於你是否清楚說明 agent 是跑在單一 Worker、使用多個 Durable Object class、提供 RPC，還是需要瀏覽器 / MCP 整合。若你想得到更好的 agents-sdk usage，請加入預期的 entrypoints、事件來源與狀態模型，不要只說「幫我做個 agent」。

提供設定與限制細節

最常見的失敗原因，是 Cloudflare 情境提供得不完整。請交出你的 wrangler.jsonc、compatibility flags、Durable Object bindings、migration 狀態，以及任何本機開發需求。當技能看得到這些限制時，就能避免給出會導致部署失敗的建議。

從可運作的薄切片開始迭代

先要求一條狹窄、端到端的路徑：安裝、設定、一個 agent class、一個 client 呼叫、一次狀態更新。等第一條路徑跑通後，再逐步擴充到 queues、workflows、串流，或可觀測性。這是驗證 agents-sdk skill 是否符合你的應用、並及早抓出 bindings 或 runtime 假設不一致的最快方式。