构建 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 等数据库。