構建 Cloudflare Workers AI 代理是從簡單的 AI 提示詞過渡到自適應工作流的下一步。這些被稱為 AI 代理（AI Agent）的系統使用大語言模型（LLM）來調用外部工具、做出決策並自主執行任務。雖然傳統的代理運行需要沈重的伺服器，但本教程將向您展示如何使用 Cloudflare Workers 和 LangChain.js 構建並託管無伺服器的 AI 代理。

TL;DR

  • 瞭解 AI 代理：代理使用 LLM 做出決策並調用外部 API（工具/tools）來自主解決使用者查詢。
  • 在邊緣（edge）端使用 LangChain.js：LangChain.js 與 Cloudflare Workers 輕量級的 V8 運行時完全相容。
  • 編寫自訂工具：編寫自訂 JS 函數以便從 Worker 的 fetch 處理常式中獲取資料、讀取資料庫或執行邏輯。
  • 利用無伺服器綁定（bindings）：將您的代理連接到 Cloudflare D1 以進行 SQL 狀態記憶體管理，或連接到 KV 進行會話快取。
  • 實施安全護欄和逾時機制：防止無限執行循環並控制 Token API 成本。

什麼是 AI 代理？

標準的聊天機器人是一個簡單的請求-回應循環：您發送提示詞，模型返回文本。相比之下，Cloudflare Workers AI 代理可以自主運行。您定義代理的目標並為其提供一組“工具”（調用 API、搜尋資料庫或執行算術運算的自訂 JavaScript 函數）。模型將決定調用哪些工具，檢查工具的輸出，並持續循環直到解決您的請求。這種代理邏輯非常適合複雜的客戶支援、後台自動化和資料庫管理。有關設置基本邊緣 API 的詳細資訊，請參閱我們關於 使用 Cloudflare Workers 構建無伺服器 API 的指南。

前提條件

在開始之前，請確保您具備以下條件：

  • 啟用了 Workers 功能的 Cloudflare 帳戶（免費計劃已足夠）。
  • Node.js 18 或更高版本以及 Wrangler CLI（安裝命令：npm install -g wrangler）。
  • OpenAI API 金鑰，或 LangChain.js 支持的其他供應商的憑據。
  • 對 JavaScript Promise 和 Workers 的 fetch 處理常式有基本瞭解。

安裝您需要的 LangChain 套件。由於 Workers 強制執行壓縮後的包大小限制，建議按需導入，而不是拉入整個框架：

 1{
 2  "dependencies": {
 3    "@langchain/openai": "^0.3.0",
 4    "@langchain/core": "^0.3.0",
 5    "langchain": "^0.3.0"
 6  },
 7  "devDependencies": {
 8    "wrangler": "^3.0.0"
 9  }
10}

將 LangChain.js 與 Workers 整合

LangChain 是構建 LLM 應用的流行框架。其 JavaScript 版本 (LangChain.js) 專為在 Web 標準 API 上運行而設計，使其與 Cloudflare 的輕量級 V8 運行時完全相容。

首先，在 Worker 的 fetch 處理常式中初始化代理：

 1import { ChatOpenAI } from "@langchain/openai";
 2import { initializeAgentExecutorWithOptions } from "langchain/agents";
 3import { DynamicTool } from "@langchain/core/tools";
 4
 5export default {
 6  async fetch(request, env) {
 7    // 1. Define custom tools for the agent
 8    const databaseTool = new DynamicTool({
 9      name: "DatabaseQuery",
10      description: "Queries the customer database for billing status.",
11      func: async (input) => {
12        // Query database (e.g. Cloudflare D1)
13        return `Customer ${input} billing status is Active.`;
14      }
15    });
16
17    const tools = [databaseTool];
18
19    // 2. Initialize the reasoning model
20    const model = new ChatOpenAI({ 
21      apiKey: env.OPENAI_API_KEY,
22      modelName: "gpt-4o-mini"
23    });
24
25    // 3. Create the executor
26    const executor = await initializeAgentExecutorWithOptions(tools, model, {
27      agentType: "openai-functions",
28    });
29
30    // 4. Run the query
31    const result = await executor.call({ input: "Check status for Customer 101" });
32    return Response.json(result);
33  }
34};

此設置完全在邊緣運行，貼近您的使用者，冷啟動時間幾乎為零。如果您想配置本地的無伺服器模型而不是調用 OpenAI，請探索我們的 Cloudflare Workers AI 教程 。

配置 Worker 專案

LangChain.js 依賴於一些 Node.js 內置模組，因此在您啟用 nodejs_compat 標誌之前，您的 Worker 將無法編譯。在 wrangler.toml 中配置它，以及您的工具所使用的任何綁定：

1name = "ai-agent-worker"
2main = "src/index.js"
3compatibility_date = "2024-09-23"
4compatibility_flags = ["nodejs_compat"]
5
6[[d1_databases]]
7binding = "DB"
8database_name = "agent-memory"
9database_id = "<your-database-id>"

切勿在程式碼中硬編碼 API 金鑰。建議將其存儲為加密的機密資料（secret）：

1npx wrangler secret put OPENAI_API_KEY

對於本地開發，請將相同的值放入 .dev.vars 文件中（並添加到 .gitignore），以便 wrangler dev 能夠讀取它，同時避免在版本控制中暴露金鑰。

管理狀態和代理記憶

由於無伺服器 Workers 在請求之間是無狀態的，您必須為代理提供一個記憶系統來存儲對話歷史記錄。

您可以將您的代理連接到無伺服器 SQL 資料庫（如 Cloudflare D1）。當代理收到請求時，它會查詢 D1 以獲取先前的消息上下文，將其傳遞給推理模型，然後將新的回應保存回資料庫。要瞭解如何設置關係型表結構，請參閱 Cloudflare D1 邊緣資料庫設置 。

在實踐中，一個極簡的消息存儲僅需要兩個輔助函數：一個用於載入歷史記錄，另一個用於追加每個新回合的消息。使用 CREATE TABLE messages (id INTEGER PRIMARY KEY, session_id TEXT, role TEXT, content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP); 創建表，然後進行配置：

 1async function loadHistory(db, sessionId) {
 2  const { results } = await db
 3    .prepare(
 4      "SELECT role, content FROM messages WHERE session_id = ? ORDER BY created_at ASC"
 5    )
 6    .bind(sessionId)
 7    .all();
 8  return results ?? [];
 9}
10
11async function saveMessage(db, sessionId, role, content) {
12  await db
13    .prepare("INSERT INTO messages (session_id, role, content) VALUES (?, ?, ?)")
14    .bind(sessionId, role, content)
15    .run();
16}

在每次請求開始時載入歷史記錄，將其作為先前的上下文傳遞給模型，然後在返回回應之前保存使用者輸入和代理的最終回答。對於無需持久保存資料的短效會話，Cloudflare KV 是比 D1 更經濟的選擇。

生產環境中的安全護欄與成本控制

因為代理以循環方式運行（推理 → 工具執行 → 推理），定義不完善的代理可能會進入無限循環，從而導致您的 API 帳單急劇上升。

  • 設置最大迭代次數：限制代理可以執行的最大循環次數（例如，限制為 5 次）。
  • 配置逾時時間：Cloudflare Workers 強制執行 CPU 執行時間限制。確保您的工具能快速返回回應以防止請求被取消。
  • 實施速率限制 (Rate Limiting)：通過應用速率限制保護您的邊緣端點免受惡意 Token 消耗。

在程式碼中，執行器選項顯式地配置了前兩個安全護欄：

1const executor = await initializeAgentExecutorWithOptions(tools, model, {
2  agentType: "openai-functions",
3  maxIterations: 5,
4  earlyStoppingMethod: "generate",
5  verbose: false,
6});

設置 maxIterations 後，即使模型尚未產生最終回答，循環也會在五次推理週期後停止，這限制了每次請求最壞情況下的 Token 開銷。

有關上下文管理的詳細分析，請參閱我們關於 構建 OpenAI API 聊天機器人 的指南。

常見陷阱與故障排除

大多數首次部署失敗都是由少數可預測的原因造成的。下表將您可能遇到的錯誤與其原因和解決方法進行了映射：

異常現象可能的原因解決方法
構建時提示 Cannot find module 'node:async_hooks'缺失 nodejs_compat 標誌添加 compatibility_flags = ["nodejs_compat"] 和最近的 compatibility_date
部署時包大小超過限制桶導入（Barrel imports）拉入了整個框架從特定的子路徑導入（如 @langchain/openai）並剔除未使用的工具
OPENAI_API_KEY is not definedSecret 未設置，或本地缺失 .dev.vars運行 wrangler secret put；在 .dev.vars 中為 wrangler dev 添加金鑰
負載下請求逾時慢速工具或失控的循環降低 maxIterations；在每個工具的 func 中加入逾時處理邏輯
代理忽略了本應使用的工具工具的 description（描述）過於模糊重寫描述以準確說明模型應當在何時調用它

這裡有兩個細節值得注意。首先，Workers 區分了實際流逝時間與 CPU 時間：等待 LLM 或資料庫回應計為 I/O，不計入 CPU 時間，因此長時間的模型調用本身很少超出 CPU 限制，但緊密循環中繁重的 JSON 解析可能會。其次，代理決策的質量很大程度上取決於您如何描述其工具。將每個 description 欄位都視為一個提示詞，並具體說明它期望的輸入結構，否則模型可能會調用錯誤的工具。

測試與部署到生產環境

在發布之前，先在本地運行時進行開發。wrangler dev 在 Cloudflare 在生產中使用的相同 Workerd 引擎中運行您的 Worker，因此其行為與邊緣端極為接近：

1npx wrangler dev      # local iteration with hot reload
2npx wrangler deploy   # publish to the edge

上線後，您需要對代理的推理循環具有可見性。啟用可觀測性，以便捕獲工具調用和錯誤，然後即時流式傳輸日誌：

1[observability]
2enabled = true

使用 npx wrangler tail 即時監控請求。除了日誌記錄之外，以下習慣能讓生產環境中的代理保持健康：在使用者輸入到達與資料庫交互的工具之前對其進行驗證和清洗；當模型超出迭代上限時返回一個友好的回退（fallback）消息，而不是拋出原始程式碼錯誤；監控每個會話的 Token 使用量，以防單個惡意調用者耗盡您的預算。對於高吞吐量的業務，可以考慮流式傳輸回應，以便使用者在生成輸出時就能看到它，而不是等待整個循環結束。

核心要點

  • AI 代理使用推理模型來決定調用哪些自訂工具以解決複雜的查詢。
  • LangChain.js 能在 Cloudflare Workers 輕量級的 V8 隔離運行時中高效運行。
  • 將自訂工具定義為連接到資料庫、API 或檔案的 JavaScript 函數。
  • 通過使用 Cloudflare D1 無伺服器 SQL 資料庫，在無狀態請求之間持久化代理記憶。
  • 實施循環迭代上限和請求逾時，以控制 API 成本並防止執行崩潰。

擴充您的代理工作流

構建生產級的 AI 代理需要無伺服器架構、資料庫工程和提示詞設計方面的專業知識。Mecanik 提供專業的 AI整合服務 ，並通過 招募網頁開發人員 頁面提供專屬工程師支援。我們構建運行快速、安全的代理系統，實現營運自動化並乾淨地擴充。歡迎今天聯絡我們，共同探討您的下一次構建。

常見問題（FAQ）

AI 聊天機器人和 AI 代理有什麼區別？ AI 聊天機器人僅針對提示詞返回文本回答。AI 代理是自主運行的：它評估您的請求，並決定在循環中運行哪些外部 API（工具）來完成任務。

我可以在 Cloudflare Workers 上運行 LangChain 嗎？ 可以。LangChain.js 使用 Web 標準 API 進行設計，使其與 Cloudflare Workers 的 V8 引擎完全相容（該引擎不運行完整的 Node.js 環境）。

如何讓 AI 代理訪問我的資料庫？ 您將資料庫查詢包裝在 LangChain 自訂工具中。當代理決定它需要資料庫資訊時，它會調用該工具函數，從而執行查詢。

如何防止 AI 代理無限循環？ 您可以在代理執行器中配置最大迭代限制（例如，maxIterations: 5），並在工具函數中實施嚴格的逾時限制。

什麼是 AI 代理最佳的託管選擇？ 像 Cloudflare Workers 這樣的無伺服器邊緣託管是理想的選擇，因為它提供全球分發、幾乎為零的冷啟動，並直接綁定到 D1 和 R2 等資料庫。