Agents

Agents SDK 是用來打造 AI 代理的工具包——這種程式能跟你對話、記住發生過的事、呼叫 AI 模型和工具，甚至能在稍後自己醒來做事。它跑在 Cloudflare Workers 上，靠 Durable Objects（持久物件）來記憶。

普通的 AI 聊天機器人，請求一結束就把一切忘光。代理不一樣：每個代理都保有自己的記憶，還能跨時間執行任務，就像一個永不疲倦、筆記永遠不會掉的私人助理。

從零打造代理，得在多台伺服器間處理記憶、即時連線和背景工作，非常麻煩。Agents SDK 把這些全包進一個類別（class），讓你專心設計代理的行為，而不是搞底層水管。

1. 用範本建立專案

   一個指令就能建好可立即執行的代理專案，聊天、工具和排程都已接好。

   bashcontent_copy複製

   npm create cloudflare@latest agents-starter -- --template cloudflare/agents-starter
   cd agents-starter
   npm install
   npm run dev

2. 設定代理的繫結

   代理就是 Durable Objects。在 wrangler.jsonc 註冊你的類別，並加一段使用 new_sqlite_classes 的遷移設定，讓每個代理都有自己的 SQL 資料庫。

   jsonccontent_copy複製

   {
     "name": "my-agent",
     "main": "src/index.ts",
     "compatibility_date": "2025-06-01",
     "durable_objects": {
       "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
     },
     "migrations": [
       { "tag": "v1", "new_sqlite_classes": ["MyAgent"] }
     ]
   }

3. 撰寫代理類別

   繼承 Agent 類別。onRequest 處理 HTTP，this.setState 儲存記憶，this.schedule 預約未來工作。routeAgentRequest 會把進來的請求導向正確的代理。

   tscontent_copy複製

   import { Agent, routeAgentRequest } from "agents";
   
   export class MyAgent extends Agent {
     async onRequest(request) {
       const count = (this.state?.count ?? 0) + 1;
       this.setState({ count });
       // run a task 10 seconds from now
       this.schedule(10, "remind", { note: "follow up" });
       return Response.json({ visits: count });
     }
   
     async remind(payload) {
       console.log("Scheduled task ran:", payload.note);
     }
   }
   
   export default {
     async fetch(request, env) {
       return (
         (await routeAgentRequest(request, env)) ||
         new Response("Not found", { status: 404 })
       );
     }
   };

4. 部署上線

   一個指令就能把代理發佈到 Cloudflare 全球網路。

   bashcontent_copy複製

   wrangler deploy

• 用 agents-starter 範本——它已內建串流聊天、工具和人工審核（human-in-the-loop）。
• 把 Workers AI、OpenAI 或 Anthropic 接上來當代理的『大腦』。
• 每位使用者或每份文件配一個代理，記憶才乾淨又獨立。
• 前面加上 AI Gateway，補上紀錄、快取和成本上限。