Cloudflare Workers 边缘计算平台搭建 AI Agent 实战指南

1. 从标题到本质：cloudflare-os 到底在讲什么

第一次看到 "cloudflare-os" 这个词，很多人会下意识以为 Cloudflare 出了一款操作系统，能装到电脑或者服务器上。我一开始也是这么理解的，直到把它的来龙去脉捋清楚，才发现这个叫法其实是一种"社区昵称"，它真正指向的是Cloudflare Workers 这套边缘计算平台，加上围绕它长出来的一整套开发范式、运行时能力和 AI Agent 基础设施。换句话说，它不是 Windows、Linux 那种传统意义的 OS，而是一个"跑在全球边缘节点上的应用运行环境"，你可以把它理解成"给代码和 AI Agent 用的云端操作系统"。

这个项目标题背后真正值得聊的东西有三层。第一层是Cloudflare Workers 本身：一个基于 V8 隔离沙箱的 Serverless 运行时，代码部署到全球几百个边缘节点，冷启动几乎可以忽略，按请求计费。第二层是围绕 Workers 构建的完整生态：KV 存储、D1 数据库、R2 对象存储、Durable Objects 有状态计算、Queues 队列、AI Gateway、Vectorize 向量数据库等等，这些拼在一起，确实有了一点"操作系统"的味道——有计算、有存储、有状态、有网络、有 AI 能力。第三层，也是最近热度最高的，是在 Workers 上搭建 AI Agent：把大模型调用、工具调用、记忆管理、多 Agent 协作全部塞进边缘运行时里。

为什么这个词最近突然火了？因为 AI Agent 开发正处在一个"基础设施焦虑"的阶段。大家发现，写一个能跑通的 Agent demo 很容易，但要让它 7x24 稳定运行、低延迟响应、全球可用、还要控制成本，就非常难。传统做法是租一台云服务器，装 Python 环境，跑 FastAPI，接各种模型 API，然后自己处理并发、扩缩容、状态持久化。这套东西维护起来很累。而 Cloudflare Workers 这套体系，恰好把很多脏活累活接管了：你不用管服务器、不用管扩容、不用管全球部署，写个函数部署上去，它自己就在边缘跑起来了。

所以这篇内容适合谁看？如果你是想入门 AI Agent 开发但被服务器运维劝退的开发者，或者你是已经在用 Workers 但还没把它和 AI Agent 结合起来的中前端工程师，又或者你是在评估边缘计算方案的技术负责人，那这篇东西应该能给你一些可以直接抄作业的思路。我会尽量把原理讲透，把坑标出来，把能复现的步骤写清楚。需要说明的是，下面涉及的一些具体配置和参数，是基于我自己的实践和社区常见做法补充的，官方文档更新很快，落地时以最新文档为准。

2. 为什么是 Workers：边缘运行时的设计取舍

2.1 传统 Serverless 和边缘运行时的核心差异

要理解 cloudflare-os 这个概念的吸引力，得先搞清楚 Workers 和传统 Serverless（比如 AWS Lambda）到底差在哪。很多人以为两者差不多，都是"上传代码、按需执行"，但底层模型完全不同。

AWS Lambda 这类传统 FaaS，本质上是容器化的。每个函数实例跑在一个轻量容器里，冷启动时要拉起容器、加载运行时、初始化代码，这个过程通常几百毫秒到几秒不等。为了减少冷启动，厂商会做"预热"，但预热又带来成本问题。而且 Lambda 默认部署在某个区域，你要全球低延迟，就得在多个区域分别部署，然后自己做流量调度。

Workers 走的是另一条路：V8 Isolate。它不是给每个函数开一个容器，而是在同一个 V8 进程里开多个隔离的 JavaScript 执行环境。Isolate 的启动成本极低，官方数据是冷启动可以做到 5 毫秒以内，很多情况下甚至是 0 毫秒——因为请求来了直接就在已经跑着的 Isolate 里执行。这个差异带来的直接好处是：你可以把很细粒度的逻辑拆成函数，而不用担心冷启动惩罚。这对 AI Agent 特别重要，因为 Agent 的执行流程往往是"多次小步骤调用"，如果每一步都有冷启动，体验会很差。

另一个关键差异是部署位置。Workers 的代码会被分发到全球数百个边缘节点，用户请求打到哪个节点，代码就在哪个节点执行。这意味着一个在东京的用户和一个在法兰克福的用户，访问同一个 Worker，延迟都是本地级别的。对于 AI Agent 来说，如果你的 Agent 需要调用多个工具、多次往返，网络延迟会被放大，边缘执行能显著改善这一点。

不过这里有个必须说清楚的取舍：V8 Isolate 不是完整的 Node.js 环境。它没有完整的文件系统、没有原生模块、没有child_process、很多 Node 内置模块要么不支持要么需要 polyfill。这是为了安全和轻量做的妥协。所以你不能把一坨依赖复杂原生库的 Python 或 Node 项目直接搬上来。你得用 Web 标准 API（fetch、Request、Response、crypto 等）来写，或者用 Workers 提供的兼容层。

2.2 从"函数"到"操作系统"：生态拼图

单看 Workers 本身，它只是个运行时。但 Cloudflare 这些年围绕它补齐了一整套基础设施，这才让"cloudflare-os"这个叫法有了底气。我把关键组件列一下，方便你建立全局认知：

这张表不是严谨的对应关系，但能帮你快速理解：当这些组件组合起来，你确实可以在上面"运行一个完整的应用"，而不只是"跑一个函数"。尤其是 Durable Objects，它解决了 Serverless 最头疼的"状态"问题。传统 Serverless 是无状态的，你要存状态就得外接数据库，每次读写都是网络往返。Durable Objects 提供了一个"有状态的单实例"，你可以把它当成一个长期存活的对象，里面可以存内存状态，同时它又有全局唯一的名字，可以做协调。这对 AI Agent 的会话管理、多 Agent 协作、任务队列来说，是非常关键的拼图。

2.3 AI Agent 为什么特别适合这套体系

现在说说为什么 AI Agent 开发者会对这套东西感兴趣。一个典型的 AI Agent 执行流程是这样的：接收用户输入 → 调用大模型做推理 → 模型决定调用某个工具 → 执行工具 → 把结果回传给模型 → 模型继续推理 → 可能再调用工具 → 最终返回结果。这个流程里，模型调用是慢的（几百毫秒到几秒），工具调用可能是快的（几十毫秒），而且步骤数不确定。

如果用传统服务器跑，你会遇到几个问题。第一，并发上来了要扩容，扩容要时间，扩容期间请求堆积。第二，Agent 的每一步都要读写状态（对话历史、工具结果、中间变量），如果状态存在远端数据库，每次读写都是延迟。第三，全球用户访问同一个服务器，远端用户延迟高。第四，模型调用可能失败、可能限流，你需要重试、降级、缓存，这些逻辑写起来很烦。

Workers 这套体系恰好对症：边缘执行降低往返延迟，Durable Objects 提供低延迟有状态会话，AI Gateway 统一处理模型调用的缓存、重试、限流，Queues 处理异步任务，Vectorize 处理记忆检索。你不需要自己搭这一整套，平台已经给你了。这就是为什么最近"agent + Workers"的组合讨论度这么高。

不过我得泼一盆冷水：这套东西不是银弹。V8 Isolate 的限制意味着你不能随便用 npm 上的库，很多库依赖 Node 原生模块，搬上来会报错。AI Agent 常用的 LangChain、LlamaIndex 这类框架，在 Workers 上跑起来是有坑的，要么用它们的轻量版本，要么自己手写编排逻辑。另外，Durable Objects 的计费模型和普通 Workers 不一样，用不好成本会上去。这些后面会细说。

3. 核心能力拆解：搭建 Agent 需要哪些积木

3.1 计算层：Worker 与 Durable Object 的分工

在 Workers 上搭 Agent，第一件事是想清楚哪些逻辑放无状态 Worker，哪些放 Durable Object。这个分工搞错了，后面会很痛苦。

无状态 Worker 适合放纯函数式的逻辑：比如解析请求、调用模型 API、格式化输出、做简单的工具调用（比如查天气、算数学）。这些逻辑不依赖之前的状态，来一个请求处理一个，处理完就结束。它们的优势是可以无限水平扩展，平台自动帮你调度。

Durable Object 适合放需要状态和协调的逻辑：比如一个用户的对话会话、一个多 Agent 协作的任务编排、一个需要串行处理的任务队列。Durable Object 的特点是全局唯一命名 + 单实例串行执行。你给它一个名字（比如用户 ID），所有对这个名字的请求都会路由到同一个实例，并且这个实例内部是串行处理请求的。这天然解决了并发写冲突的问题。

我踩过的一个坑是：一开始把所有逻辑都塞进 Durable Object，觉得"有状态方便"。结果发现 Durable Object 的吞吐是有限的，因为它是单实例串行，如果所有用户都路由到少数几个实例，就会成为瓶颈。正确做法是按用户或会话分片，每个用户一个 Durable Object 实例，这样并发就分散开了。命名策略很关键，通常用userId或者sessionId作为 Durable Object 的名字。

还有一个细节：Durable Object 的状态可以存在内存里（快，但实例被回收就没了），也可以存到它的持久化存储里（慢一点，但可靠）。对于对话历史这种不能丢的数据，要定期持久化；对于临时缓存，放内存就行。官方推荐的做法是内存 + 定期持久化结合，兼顾性能和可靠性。

3.2 存储层：KV、D1、R2、Vectorize 怎么选

存储选型是另一个容易搞混的地方。我见过有人用 KV 存对话历史，结果发现查询很不方便；也有人用 D1 存大文件，结果数据库膨胀得很快。这里给一个简单的判断标准：

• KV：适合存"读多写少、按 key 直接取"的数据。比如配置、feature flag、简单的缓存。它的写入有延迟（全球同步需要时间），不适合频繁更新的数据。不要用 KV 存需要复杂查询的数据，它只支持按 key 取，不支持条件查询。
• D1：适合存"需要 SQL 查询"的结构化数据。比如用户表、订单表、日志表。它是 SQLite 的分布式版本，支持标准 SQL。但要注意，D1 的写入也是分布式的，有主从复制的延迟，不适合超高并发的写入场景。
• R2：适合存"大文件、二进制数据"。比如用户上传的图片、模型文件、备份。它的最大卖点是没有出口流量费，读取不花钱，这在存大量文件时能省很多。
• Vectorize：适合存"向量嵌入"，用于语义检索。AI Agent 的长期记忆、知识库检索都靠它。你把文本转成向量存进去，查询时用相似向量检索。

对于 AI Agent 的对话历史，我的建议是：热数据放 Durable Object 内存，温数据放 D1，冷数据归档到 R2。对话历史需要按会话查询，D1 的 SQL 能力正好合适。如果对话很长，可以把老对话压缩后存 R2，需要时再取回来。

3.3 AI 能力层：AI Gateway 与 Workers AI

模型调用是 Agent 的核心。这里有两个东西要搞清楚：AI Gateway和Workers AI。

AI Gateway 是一个代理层，你把它放在你的应用和模型提供商之间。它的价值在于：统一管理多个模型提供商的 API key、缓存相同请求的响应（省钱）、限流和重试（提高稳定性）、记录日志和用量（方便排查）。比如你的 Agent 调用 OpenAI 的接口，如果两个用户问了同样的问题，AI Gateway 可以直接返回缓存结果，不用再花钱调模型。对于高频重复的查询，这个缓存能省不少钱。

Workers AI 则是平台内置的模型推理服务。你可以直接在 Worker 里调用它提供的模型（比如文本生成、图像识别、嵌入模型），不用自己接第三方 API。它的优势是延迟低（因为和你的 Worker 在同一个网络里）、计费简单（按推理量算）、无需管理 API key。劣势是模型选择相对有限，如果你需要最新的、最强的模型，可能还是得接第三方。

我的实践建议是：用 AI Gateway 做统一入口，把 Workers AI 和第三方模型都挂在后面。简单任务、对延迟敏感的任务走 Workers AI；复杂推理、需要最强模型的任务走第三方。AI Gateway 帮你做路由和缓存，你只需要在代码里指定用哪个。

3.4 编排层：Queues 与 Workflows

Agent 的执行往往不是一步到位的，可能需要异步处理、需要重试、需要多步骤编排。这时候 Queues 和 Workflows 就派上用场了。

Queues 是消息队列，适合解耦生产者和消费者。比如用户提交一个任务，你先把任务丢进队列，然后由消费者 Worker 慢慢处理，处理完再通知用户。这样用户不用等待，系统也不会因为突发流量被打垮。

Workflows 是持久化的多步骤编排。你可以定义一个工作流，包含多个步骤，每个步骤可以等待、可以重试、可以分支。如果中间某一步失败了，Workflows 会记录状态，可以从失败的地方继续，而不是从头再来。这对长流程的 Agent 任务特别有用，比如"抓取数据 → 分析 → 生成报告 → 发送邮件"这种多步骤流程。

我个人的经验是：短任务、实时性要求高的用 Worker 直接处理；长任务、可以异步的用 Queues；多步骤、需要状态和重试的用 Workflows。不要一上来就上 Workflows，它的学习成本和调试成本都比直接写 Worker 高，简单场景没必要。

4. 实操：从零搭一个边缘 AI Agent

4.1 环境准备与项目初始化

先说工具链。你需要 Node.js（建议 18 以上）和 npm，然后安装 Wrangler，这是 Cloudflare 官方的 CLI 工具。安装命令是：

npm install -g wrangler

装完之后登录：

wrangler login

这会打开浏览器让你授权。授权完成后，你就可以用 Wrangler 创建项目、部署、查看日志了。

创建一个新项目：

npm create cloudflare@latest my-agent

这个命令会问你几个问题：项目类型选 "Hello World Worker"，语言选 TypeScript（强烈建议用 TS，类型提示能帮你避开很多坑），是否用 Git 选是。创建完成后进入目录：

cd my-agent

项目结构大概是这样的：src/index.ts是入口，wrangler.toml是配置文件，package.json是依赖。先跑一下本地开发服务器：

npm run dev

它会启动一个本地服务器，通常在http://localhost:8787。访问一下，看到 "Hello World" 就说明环境 OK 了。

这里有个实操心得：Wrangler 的本地开发模式（wrangler dev）默认是在本地模拟 Workers 运行时，用的是 Miniflare。它和线上环境有细微差异，比如某些 API 的行为、绑定的模拟。所以本地跑通不代表线上一定跑通，部署后一定要再测一遍。我踩过的坑是本地 KV 绑定正常，线上因为命名空间 ID 配错导致读不到数据，排查了半天。

4.2 配置绑定：把存储和 AI 能力接进来

接下来要在wrangler.toml里配置各种绑定。绑定就是告诉 Worker "你可以用哪些资源"。一个典型的 Agent 项目配置大概长这样：

name = "my-agent" main = "src/index.ts" compatibility_date = "2024-09-23" [[kv_namespaces]] binding = "AGENT_KV" id = "你的KV命名空间ID" [[d1_databases]] binding = "AGENT_DB" database_name = "agent-db" database_id = "你的D1数据库ID" [[durable_objects.bindings]] name = "AGENT_SESSION" class_name = "AgentSession" [[migrations]] tag = "v1" new_classes = ["AgentSession"] [ai] binding = "AI" [[vectorize]] binding = "VECTOR_INDEX" index_name = "agent-memory"

几个关键点解释一下。compatibility_date很重要，它决定了你的 Worker 用哪个版本的运行时行为。Cloudflare 会不断更新运行时，但为了不破坏已有代码，新行为只在新的 compatibility date 后生效。建议设成你开始项目那天的日期，这样行为可预期。

Durable Objects 需要migrations配置，这是用来管理类的版本变更的。第一次创建用new_classes，后续如果要重命名或删除类，要用renamed_classes或deleted_classes。这个机制一开始容易忘，部署时报错说类不存在，多半是 migration 没配。

KV、D1、Vectorize 都需要先在 Cloudflare 控制台创建，拿到 ID 填进来。D1 创建后还要执行建表 SQL：

wrangler d1 execute agent-db --file=./schema.sql

schema.sql里写你的建表语句。本地开发时可以用--local参数在本地 SQLite 里执行，避免污染线上数据。

4.3 写一个带记忆的对话 Agent

现在写核心逻辑。一个最小的带记忆的对话 Agent，流程是：接收用户消息 → 从 Durable Object 取出对话历史 → 调用模型生成回复 → 把新消息存回历史 → 返回回复。

先定义 Durable Object 类：

export class AgentSession { state: DurableObjectState; history: Array<{ role: string; content: string }> = []; constructor(state: DurableObjectState) { this.state = state; this.state.blockConcurrencyWhile(async () => { const stored = await this.state.storage.get("history"); if (stored) this.history = stored as any[]; }); } async fetch(request: Request) { const { message } = await request.json() as { message: string }; this.history.push({ role: "user", content: message }); const response = await fetch("https://api.openai.com/v1/chat/completions", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${this.state.env.OPENAI_KEY}` }, body: JSON.stringify({ model: "gpt-4o-mini", messages: this.history }) }); const data = await response.json() as any; const reply = data.choices[0].message.content; this.history.push({ role: "assistant", content: reply }); await this.state.storage.put("history", this.history); return new Response(JSON.stringify({ reply }), { headers: { "Content-Type": "application/json" } }); } }

这里有几个关键设计。blockConcurrencyWhile保证在加载历史完成前，不会有其他请求进来处理，避免读到空历史。历史存在storage里，是持久化的，实例被回收后重新加载也能恢复。每次对话后都put一次，保证不丢。

然后是入口 Worker：

export default { async fetch(request: Request, env: Env) { const url = new URL(request.url); const userId = url.searchParams.get("userId") || "default"; const id = env.AGENT_SESSION.idFromName(userId); const stub = env.AGENT_SESSION.get(id); return stub.fetch(request); } }

这个入口的作用是按 userId 路由到对应的 Durable Object 实例。同一个用户的所有请求都会打到同一个实例，历史自然就串起来了。不同用户之间互不干扰。

注意事项：idFromName是根据名字生成 ID，同样的名字永远生成同样的 ID，这是分片的基础。但名字的选择要小心，如果用用户输入直接当名字，可能被恶意构造。建议用内部生成的稳定 ID，或者对用户输入做哈希。

4.4 接入工具调用与向量记忆

上面的 Agent 只会聊天，真正的 Agent 要能调用工具。工具调用的实现方式是：在给模型的请求里带上工具定义，模型返回tool_calls时，你执行对应工具，把结果再回传给模型。

工具定义大概长这样：

const tools = [{ type: "function", function: { name: "get_weather", description: "查询指定城市的天气", parameters: { type: "object", properties: { city: { type: "string", description: "城市名" } }, required: ["city"] } } }];

模型返回tool_calls后，你解析出函数名和参数，执行对应逻辑，然后把结果作为role: "tool"的消息追加到历史里，再调一次模型。这个循环可能要跑几轮，直到模型不再请求工具。

向量记忆则是另一条线。当对话历史很长时，不可能全部塞进上下文（有 token 限制，而且贵）。做法是：把历史消息转成向量存进 Vectorize，每次新消息来时，先检索最相关的几条历史，只把这几条塞进上下文。这样既保留了长期记忆，又控制了成本。

生成向量可以用 Workers AI 的嵌入模型：

const embeddings = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [message] });

然后把向量和原文一起存进 Vectorize。检索时用同样的模型把查询转成向量，调query方法拿最相似的几条。

实操心得：向量检索的召回质量很依赖嵌入模型和分块策略。对话历史建议按"轮次"分块，而不是按固定字数切，否则会把一问一答切断，语义不完整。另外，检索回来的历史要标注清楚是"历史记忆"，避免模型把它当成当前对话。

5. 常见问题与排查技巧实录

5.1 部署与运行时的高频报错

在 Workers 上开发，报错信息和传统 Node 环境很不一样，这里整理几个我遇到最多的问题。

问题一：ReferenceError: process is not defined。这是因为 Workers 没有 Node 的process全局对象。很多 npm 库依赖它。解决办法是用nodejs_compat兼容标志，在wrangler.toml里加：

compatibility_flags = ["nodejs_compat"]

但要注意，这个标志只是提供了一部分 Node API 的 polyfill，不是全部。有些库还是跑不起来。

问题二：Error: No such module "xxx"。这通常是依赖了 Node 原生模块（比如fs、child_process）。这些在 Workers 上根本不存在，没有 polyfill 能解决。只能换库，或者自己重写这部分逻辑。

问题三：Durable Object 报Cannot read properties of undefined。多半是 migration 没配好，或者类名拼写不一致。检查wrangler.toml里的class_name和代码里export class的名字是否完全一致，migration 的new_classes是否包含这个类。

问题四：KV 读到的值是 null。先确认本地还是线上。本地开发时 KV 是模拟的，和线上数据不通。如果线上读到 null，检查命名空间 ID 是否填对，key 是否拼写一致。KV 的写入有传播延迟，刚写完立刻读可能读不到，等几秒再试。

问题五：模型调用超时。Workers 的请求有 CPU 时间限制（免费版 10ms，付费版 30s 可配置），但等待网络 IO 的时间不算 CPU 时间。不过如果模型响应特别慢，可能触发整体的请求超时。解决办法是把长任务放到 Queues 或 Workflows 里异步处理，不要阻塞在请求里。

5.2 成本控制的几个关键点

Workers 的计费模型和传统服务器不同，用不好会超预算。几个关键点：

• 请求数计费：每次 Worker 被调用算一次请求。如果你的 Agent 一次对话要调多次 Worker（比如工具调用循环），请求数会累积。优化方法是把多次调用合并到一个 Worker 里，减少往返。
• Durable Object 计费：DO 的计费包括请求数、持续时间、存储。DO 实例如果长期存活，持续时间会计费。所以不要让 DO 无谓地保持活跃，用完就让它休眠。
• AI Gateway 缓存：一定要开缓存。相同请求命中缓存不花钱，对于重复查询多的场景能省很多。
• Workers AI 用量：内置模型按推理量计费，嵌入模型调用频繁的话成本会上去。可以考虑批量处理，减少调用次数。

我个人的经验是，先用免费额度跑通，观察用量面板，找出最耗资源的环节，再针对性优化。不要一上来就过度设计。

5.3 调试与可观测性

Workers 的调试不像本地 Node 那么方便，因为代码跑在远端。几个实用手段：

• wrangler tail：实时查看线上日志，排查线上问题必备。
• console.log：在 Worker 里打日志，会出现在 tail 里。但注意日志有采样，不是每条都显示。
• 本地开发用wrangler dev，可以断点调试（配合 VS Code 的调试配置）。
• AI Gateway 的日志面板：查看每次模型调用的请求、响应、耗时、缓存命中情况，排查模型相关问题很有用。

踩过的坑：线上问题和本地不一致时，优先怀疑环境差异——绑定配置、compatibility date、环境变量。我遇到过一次本地正常线上报错，最后发现是环境变量在线上没配，env.OPENAI_KEY是 undefined。

5.4 常见问题速查表

6. 这套方案适合什么、不适合什么

聊了这么多实现细节，最后说说适用边界，这比单纯讲"怎么做"更重要。

适合的场景：面向全球用户的轻量级 AI 应用、对延迟敏感的对话 Agent、需要快速上线验证的产品原型、流量波动大不想管服务器的项目、需要边缘就近处理的任务。这些场景下，Workers 的免运维、全球部署、按量计费优势非常明显。

不太适合的场景：需要大量 CPU 计算的任务（比如本地跑大模型、视频转码）、依赖复杂 Node 生态的项目、需要长时间运行的后台进程、对数据驻留有严格要求的场景。这些场景下，传统服务器或容器方案更合适。

我个人的判断是，Workers 最适合做 Agent 的"编排层"和"接入层"，而不是"计算层"。把请求接入、会话管理、工具调度、模型路由放在 Workers 上，把重计算任务外包给专门的服务，这样各取所长。硬要把所有东西都塞进 Workers，会撞上运行时的各种限制，得不偿失。

另外，这套体系还在快速演进，新的绑定、新的能力不断加进来。我的建议是保持关注但不要盲目追新，先把核心的 Worker + Durable Object + AI Gateway 这套组合用熟，等新能力稳定了再逐步引入。技术选型上，稳定压倒一切，尤其是生产环境。

最后分享一个我自己的小习惯：每次上线新功能前，先用wrangler dev在本地把主流程跑通，再用wrangler deploy --dry-run检查配置有没有问题，最后才正式部署，部署完立刻wrangler tail盯几分钟日志。这套流程帮我拦下了不少低级错误，尤其是配置类的，dry-run 能提前发现大部分问题。