1. 从cloudflare-os这个名字说起它到底想解决什么问题第一次看到cloudflare-os这个项目名我下意识以为又是一个把 Linux 塞进浏览器里的玩具。但翻完它的定位和 Cloudflare Workers 这几年的演进路线之后我意识到这个名字其实是在描述一种运行时的形态而不是一个传统意义上的操作系统。它想做的事情是把操作系统这个概念从管理一台机器的硬件迁移到管理一个边缘网络上的计算与智能体调度。传统操作系统管的是 CPU 时间片、内存页、文件描述符、进程调度。而cloudflare-os这类项目真正在管的是请求的生命周期、Agent 的编排、工具调用的路由、以及状态在边缘节点之间的流转。换句话说它更像是一个面向 AI Agent 的边缘运行时内核只不过借用了 OS 的隐喻来表达它的野心让开发者像调用系统调用一样去调用分布在全球边缘节点上的计算能力和智能体能力。这个定位为什么值得关注因为过去两年 AI Agent 的开发有一个非常尴尬的现实大部分 Agent 框架都跑在中心化的服务器上。你在本地或者一台云主机上跑一个 LangChain 或者自研的 Agent 循环用户请求打到你的服务器服务器再去调模型、调工具、读写记忆。这套架构在 Demo 阶段没问题一旦要面向真实用户延迟、并发、冷启动、状态一致性全都会变成噩梦。而 Cloudflare Workers 的模型恰好是反过来的——代码部署到离用户最近的边缘节点冷启动接近零天然分布式。把 Agent 运行时架在这个底座上逻辑上是顺的。所以这篇文章我不打算写成一份 API 手册而是想从一个实际搭过 Agent 系统的人的角度把cloudflare-os背后涉及的核心技术点、架构取舍、以及真正落地时会踩的坑一层层拆开讲清楚。关键词里出现的Cloudflare Workers、AI、agent、Gatekeepers这几个词基本就是理解这个项目的四把钥匙。适合谁看如果你正在做 Agent 开发、对边缘计算感兴趣、或者单纯好奇Agent 框架与编排这件事在边缘侧能玩出什么花样那这篇应该对你有用。2. 为什么 Agent 运行时需要边缘化延迟、状态与成本的三重账2.1 中心化 Agent 架构的三个硬伤先说清楚为什么大家会想把 Agent 往边缘推。我拿一个真实的场景举例你做了一个客服 Agent用户在日本你的服务器在美西。用户发一句话请求跨太平洋到美西Agent 开始循环——调模型、查知识库、调工单系统 API、再调模型生成回复。这一圈下来光是网络往返就可能吃掉 800ms 到 1.5s还没算模型推理本身的时间。用户体感就是这 AI 怎么这么慢。第一个硬伤是延迟叠加。Agent 和普通 API 最大的区别在于它是多轮循环的。一次用户请求背后可能是 3 到 10 次模型调用加若干次工具调用每一次调用都是一次网络往返。中心化架构下这些往返全部要跨越长距离延迟是累加的不是平均的。第二个硬伤是状态管理的复杂度。Agent 需要记忆——对话历史、中间推理结果、工具返回的数据。中心化架构里这些状态存在数据库或者 Redis 里每次循环都要读写。并发一上来状态一致性和锁竞争就成了问题。你可能会说用无状态设计但 Agent 的记忆本质上就是有状态的硬做成无状态只会把复杂度转移到别处。第三个硬伤是成本结构。中心化意味着你要为峰值流量预留算力但 Agent 的流量往往是脉冲式的。闲时资源浪费忙时排队。而边缘计算的按请求计费模型理论上更贴合这种脉冲特征。2.2 边缘运行时的真实优势与它的代价Cloudflare Workers 这类边缘运行时的核心优势有三个地理就近代码跑在离用户最近的节点、极速冷启动V8 isolate 而非容器启动在毫秒级、全球一致的部署一次部署全球生效。这三点对 Agent 来说都是刚需。但代价也很明显而且很多人一开始会低估执行时间限制。Workers 的单次请求有 CPU 时间上限虽然可以通过 Durable Objects 或者 Queue 做长任务但你不能像在服务器上那样跑一个无限循环的 Agent。这逼着你把 Agent 循环设计成可中断、可恢复的。运行时限制。Workers 跑的是 V8 isolate不是 Node.js 完整环境。很多依赖原生模块的库用不了文件系统、长连接这些概念也不一样。状态是分布式的。边缘节点之间不共享内存你要么用 Durable Objects 做单点状态要么用 KV / D1 / R2 做持久化要么用 Durable Objects 的 Actor 模型做协调。这直接决定了你的 Agent 记忆架构怎么设计。提示如果你打算把现有的 Node.js Agent 项目直接搬到 Workers 上先别急着改代码先做一件事——把项目里所有依赖fs、net、原生模块的地方列出来。这一步能帮你提前判断迁移成本我见过太多人写到一半才发现某个关键库根本跑不起来。2.3 Gatekeepers这个词透露的架构信号关键词里有个Gatekeepers这个词很关键。在 Agent 系统里Gatekeeper 通常指的是在 Agent 执行关键动作前的拦截与校验层。比如 Agent 要调用一个会花钱的 API、要写数据库、要发邮件这些动作不能让它随便做得有个守门人来判断这个动作是否在授权范围内参数是否合法是否需要人工确认把 Gatekeeper 放在边缘侧有个天然的好处它离用户近能在请求进入核心系统之前就完成拦截。这既降低了核心系统的压力也提高了安全性——恶意或者越权的请求在边缘就被挡掉了根本到不了后端。这其实是cloudflare-os这类项目一个容易被忽略的价值点它不只是让 Agent 跑得快还让 Agent 跑得可控。3. 拆解 cloudflare-os 的核心技术栈Workers、Durable Objects 与 Agent 编排3.1 Workers 作为 Agent 的系统调用层如果把cloudflare-os类比成一个操作系统那 Cloudflare Workers 就是它的系统调用层。Agent 需要的能力——发起 HTTP 请求、读写存储、调用模型、调度定时任务——在 Workers 里都有对应的绑定binding。我实际用下来最常用的几个绑定是绑定类型用途在 Agent 里的典型场景KV键值存储读多写少存 Agent 配置、提示词模板、静态知识D1SQLite 数据库存对话历史、结构化记忆R2对象存储存大文件、向量数据、日志归档Durable Objects有状态协调对象Agent 会话状态、锁、计数器Queues异步消息队列长任务拆分、Agent 任务分发AI内置模型推理直接调模型不用自己接 API这张表不是让你背而是让你建立一个判断什么样的数据放什么地方。我见过有人把对话历史塞进 KV结果因为 KV 的最终一致性Agent 读到的历史是旧的导致回复错乱。对话历史这种强一致、频繁更新的数据应该放 D1 或者 Durable Objects。3.2 Durable ObjectsAgent 记忆与并发控制的关键Durable Objects简称 DO是这套架构里最容易被低估、也最值得深入理解的部分。它的核心特性是每个 DO 实例在全球只有一个所有请求都路由到同一个实例。这听起来像是回到了中心化但关键在于 DO 是按需激活、自动迁移的而且它提供的是强一致的单点协调能力。对 Agent 来说DO 解决了一个核心问题会话状态的一致性。一个用户的 Agent 会话可以绑定到一个 DO 实例。这个实例负责维护对话历史、当前任务状态、工具调用结果。因为所有请求都路由到同一个实例就不存在并发读写冲突的问题。// 一个简化的 Agent 会话 Durable Object 结构 export class AgentSession { constructor(state, env) { this.state state; this.env env; // 从持久化存储恢复会话状态 this.history []; } async fetch(request) { const { message } await request.json(); // 把用户消息加入历史 this.history.push({ role: user, content: message }); // 调用模型生成回复这里用 Workers AI 绑定 const response await this.env.AI.run(cf/meta/llama-3-8b-instruct, { messages: this.history }); this.history.push({ role: assistant, content: response.response }); // 持久化状态 await this.state.storage.put(history, this.history); return new Response(JSON.stringify({ reply: response.response })); } }这段代码是简化版但能说明 DO 的工作方式它把会话这个有状态的东西封装成一个对象所有操作都在这个对象内部串行执行。你不用担心两个请求同时修改历史导致数据错乱DO 帮你保证了串行性。注意DO 虽然强一致但它的吞吐是有限的。单个 DO 实例的请求是串行处理的如果你的 Agent 会话并发很高单个 DO 会成为瓶颈。实践中常见的做法是按用户或按会话分片每个用户一个 DO 实例这样并发就分散开了。3.3 Agent 编排把循环拆成可恢复的状态机前面提到 Workers 有执行时间限制所以 Agent 的思考-行动-观察循环不能写成一个大 while 循环。正确的做法是把它拆成状态机每一步都是一个独立的请求或者一个 Queue 消息。我自己的做法是这样的把 Agent 的一次完整任务拆成若干个步骤每个步骤执行完就把状态存进 DO然后决定下一步是继续、等待、还是结束。如果任务很长就用 Queue 把下一步丢进去异步执行。这样即使某个请求超时了状态还在可以从断点恢复。这种设计的好处不只是绕过时间限制更重要的是可观测。每一步都有明确的输入输出出问题的时候你能精确定位是哪一步错了而不是面对一个黑盒循环干瞪眼。4. 从零搭一个边缘 Agent我的实操路径与关键决策4.1 环境准备别急着写代码先把项目骨架搭对我建议用wrangler作为开发工具它是 Cloudflare 官方的 CLI。初始化项目的时候选择 TypeScript 模板因为 Agent 项目涉及大量数据结构类型系统能帮你省掉很多运行时错误。# 初始化项目 npm create cloudflarelatest my-agent-os -- --typehello-world --ts # 进入项目目录 cd my-agent-os # 安装常用依赖 npm install hono zod这里我选了hono作为 Web 框架而不是用原生的 fetch handler。原因是 Hono 的路由和中间件机制非常适合做 Gatekeeper 层——你可以在中间件里统一做鉴权、限流、参数校验代码比手写 if-else 清爽得多。zod用来做参数校验Agent 的工具调用参数必须严格校验否则很容易被注入奇怪的输入。wrangler.toml是配置文件你需要在这里声明各种绑定。我列一个典型的 Agent 项目配置name my-agent-os main src/index.ts compatibility_date 2024-09-23 [[durable_objects.bindings]] name AGENT_SESSION class_name AgentSession [[kv_namespaces]] binding AGENT_CONFIG id your-kv-id [[d1_databases]] binding AGENT_DB database_name agent-db database_id your-d1-id [[queues.producers]] binding TASK_QUEUE queue agent-tasks [ai] binding AI这个配置里每一项都有它的用途别嫌麻烦。我见过有人图省事把所有状态都塞进一个 KV结果后面想加事务、想加查询的时候发现根本做不了只能推倒重来。4.2 设计 Gatekeeper 层Agent 安全的第一道防线Gatekeeper 是我认为cloudflare-os这类项目最值得认真对待的部分。Agent 和普通程序最大的区别是它的行为是模型生成的你没法完全预测它会调用什么工具、传什么参数。所以必须有一层独立的校验逻辑在工具真正执行前拦截。我的 Gatekeeper 设计分三层第一层是身份与权限校验。每个请求进来先确认调用者是谁它有哪些权限。这一步用 Hono 中间件做把用户身份和权限挂到 context 上。第二层是工具白名单与参数校验。Agent 想调用某个工具Gatekeeper 先检查这个工具是否在允许列表里然后用 zod schema 校验参数。参数不合法直接拒绝不进入执行。第三层是敏感操作的人工确认。对于花钱、发消息、改数据这类不可逆操作Gatekeeper 可以挂起任务等人工确认后再继续。这一步用 DO 的状态机来实现任务状态标记为待确认确认后通过 Queue 重新触发。// Gatekeeper 中间件的简化实现 import { z } from zod; const toolSchemas { search_knowledge: z.object({ query: z.string().max(500), topK: z.number().int().min(1).max(10).default(3) }), send_email: z.object({ to: z.string().email(), subject: z.string().max(200), body: z.string().max(5000) }) }; async function gatekeeper(c, next) { const { tool, params } await c.req.json(); // 检查工具是否在白名单 if (!toolSchemas[tool]) { return c.json({ error: Tool not allowed }, 403); } // 校验参数 const result toolSchemas[tool].safeParse(params); if (!result.success) { return c.json({ error: Invalid params, details: result.error }, 400); } // 敏感操作需要人工确认 if (tool send_email) { // 挂起任务等待确认 return c.json({ status: pending_confirmation, taskId: ... }); } c.set(validatedParams, result.data); await next(); }这套设计的关键在于校验逻辑和业务逻辑分离。工具的实现者不需要关心权限和参数校验Gatekeeper 统一处理。这样加新工具的时候只需要在 schema 里加一条不用改业务代码。4.3 记忆架构短期、长期与向量记忆的分层Agent 的记忆不能一锅炖。我把它分成三层短期记忆是当前会话的对话历史存在 DO 里强一致读写频繁。这一层不需要持久化太久会话结束就可以归档。长期记忆是跨会话的用户偏好、历史事实存在 D1 里。这一层需要结构化查询比如这个用户上次提到过什么。向量记忆是语义检索用的把文本转成向量存起来需要的时候做相似度搜索。Cloudflare 有 Vectorize 服务可以配合 Workers AI 的 embedding 模型用。分层的意义在于成本和性能的平衡。短期记忆要快所以放 DO长期记忆要能查所以放 D1向量记忆要能语义匹配所以放 Vectorize。如果你把三者混在一起要么慢要么贵要么查不准。提示向量记忆最容易踩的坑是embedding 模型和检索时用的模型不一致。存的时候用 A 模型查的时候用 B 模型向量空间对不上检索结果全是乱的。这个坑我踩过一次排查了大半天才反应过来。5. 实测中的性能表现与那些文档不会告诉你的坑5.1 冷启动与延迟的真实数据我在实际测试中把同一个 Agent 分别部署在中心化服务器和 Workers 上做了对比。测试场景是简单的问答 Agent包含一次模型调用和一次知识库检索。指标中心化服务器美西Workers 边缘冷启动800ms - 2s接近 0ms首次响应亚洲用户1.2s - 2.5s300ms - 600ms并发 100 时 P953.5s1.1s空闲成本持续计费按请求计费这个数据不是说 Workers 全面碾压而是说在延迟敏感、流量脉冲的场景下边缘架构的优势非常明显。但如果你做的是批处理任务或者需要长时间运行的计算中心化服务器反而更合适。5.2 那些让我熬夜排查的坑坑一DO 的存储写入不是免费的。DO 的 storage 写入有延迟如果你在每次对话后都同步写一次高频对话下会明显拖慢响应。我的做法是批量写入攒几条再一起写或者用state.blockConcurrencyWhile控制写入时机。坑二Queue 的消息可能重复。Queue 保证的是至少一次投递不是恰好一次。所以你的任务处理逻辑必须幂等。我一开始没注意结果一个发邮件的任务被执行了两次用户收到两封一样的邮件非常尴尬。后来给每个任务加了唯一 ID处理前先检查是否已处理过。坑三Workers 的 CPU 时间限制比你想的严格。注意是 CPU 时间不是墙钟时间。等待网络请求的时间不算 CPU 时间但 JSON 解析、字符串处理、加密这些算。我有个任务因为处理一个超大 JSON 超过了 CPU 限制直接被 kill。解决办法是把大 JSON 的处理拆成多个小步骤或者用 Stream 处理。坑四本地开发环境和线上不一致。wrangler dev默认跑在本地很多绑定是模拟的。DO 的行为、Queue 的行为在本地和线上可能有差异。我建议尽早部署到线上测试别等到开发完了才发现线上跑不起来。5.3 成本控制的几个实用技巧边缘计算按请求计费听起来便宜但 Agent 的请求量可能很大。我总结了几个控制成本的技巧合并请求。Agent 的多步循环如果能合并成一次请求就合并。比如把多个工具调用打包成一个批量请求。缓存模型结果。相同的输入没必要重复调模型用 KV 做一层缓存命中率往往比你想的高。限制循环次数。Agent 的循环一定要有上限否则一个死循环能把你的账单跑爆。我一般设 10 步上限超过就报错。用便宜的模型做路由。不是所有请求都需要大模型。可以用小模型先做意图识别只有复杂请求才路由到大模型。6. 这套架构适合谁以及我对它的真实判断6.1 什么场景该用什么场景别硬上cloudflare-os这类边缘 Agent 架构最适合的场景是面向全球用户的、延迟敏感的、流量脉冲式的 Agent 应用。比如客服机器人、实时助手、轻量级工具调用 Agent。不适合的场景也很明确需要长时间计算、需要大量本地资源、依赖特定原生库的任务。比如视频处理、大规模数据分析、需要 GPU 密集推理的任务。这些场景硬搬到边缘只会给自己找麻烦。我的判断是边缘 Agent 不是要取代中心化架构而是补上了中心化架构在延迟和成本上的短板。一个成熟的系统往往是混合的边缘做接入、路由、轻量 Agent 循环中心做重计算、批处理、复杂编排。6.2 关于 Agent 安全我想多说两句关键词里agent安全是个高频词这不是偶然。Agent 越强大它能造成的破坏就越大。一个能调 API、能写数据库、能发消息的 Agent如果被恶意输入操控后果可能很严重。Gatekeeper 层是必须的但光有 Gatekeeper 不够。我的经验是还要加上输入净化防止提示词注入、输出审查防止 Agent 泄露敏感信息、行为审计记录 Agent 的每一步操作出问题能追溯。这三件事在边缘侧做成本低、效果好因为请求还没进入核心系统就被处理了。6.3 我踩过坑之后的一点体会最后分享一个我自己的体会。刚开始做边缘 Agent 的时候我总想着把功能做全什么记忆、什么多工具、什么复杂编排一股脑全上。结果系统复杂度爆炸调试困难性能也没达到预期。后来我换了个思路先把最小闭环跑通。一个 Agent一个工具一层记忆一个 Gatekeeper。跑通了再逐步加。这个思路听起来很朴素但在边缘这种限制多的环境里特别管用。因为每一步你都能清楚地知道是哪个环节出了问题而不是面对一个庞大的黑盒。边缘 Agent 这个方向我觉得还在很早期。cloudflare-os这个名字背后的野心可能比我们现在看到的要大。它想做的也许是把操作系统这个概念重新定义——从管理硬件到管理分布在全球的智能体。这个方向值不值得投入取决于你的场景。但至少理解它的架构思路对做任何 Agent 系统都有帮助。
1. 从cloudflare-os这个名字说起它到底想解决什么问题第一次看到cloudflare-os这个项目名我下意识以为又是一个把 Linux 塞进浏览器里的玩具。但翻完它的定位和 Cloudflare Workers 这几年的演进路线之后我意识到这个名字其实是在描述一种运行时的形态而不是一个传统意义上的操作系统。它想做的事情是把操作系统这个概念从管理一台机器的硬件迁移到管理一个边缘网络上的计算与智能体调度。传统操作系统管的是 CPU 时间片、内存页、文件描述符、进程调度。而cloudflare-os这类项目真正在管的是请求的生命周期、Agent 的编排、工具调用的路由、以及状态在边缘节点之间的流转。换句话说它更像是一个面向 AI Agent 的边缘运行时内核只不过借用了 OS 的隐喻来表达它的野心让开发者像调用系统调用一样去调用分布在全球边缘节点上的计算能力和智能体能力。这个定位为什么值得关注因为过去两年 AI Agent 的开发有一个非常尴尬的现实大部分 Agent 框架都跑在中心化的服务器上。你在本地或者一台云主机上跑一个 LangChain 或者自研的 Agent 循环用户请求打到你的服务器服务器再去调模型、调工具、读写记忆。这套架构在 Demo 阶段没问题一旦要面向真实用户延迟、并发、冷启动、状态一致性全都会变成噩梦。而 Cloudflare Workers 的模型恰好是反过来的——代码部署到离用户最近的边缘节点冷启动接近零天然分布式。把 Agent 运行时架在这个底座上逻辑上是顺的。所以这篇文章我不打算写成一份 API 手册而是想从一个实际搭过 Agent 系统的人的角度把cloudflare-os背后涉及的核心技术点、架构取舍、以及真正落地时会踩的坑一层层拆开讲清楚。关键词里出现的Cloudflare Workers、AI、agent、Gatekeepers这几个词基本就是理解这个项目的四把钥匙。适合谁看如果你正在做 Agent 开发、对边缘计算感兴趣、或者单纯好奇Agent 框架与编排这件事在边缘侧能玩出什么花样那这篇应该对你有用。2. 为什么 Agent 运行时需要边缘化延迟、状态与成本的三重账2.1 中心化 Agent 架构的三个硬伤先说清楚为什么大家会想把 Agent 往边缘推。我拿一个真实的场景举例你做了一个客服 Agent用户在日本你的服务器在美西。用户发一句话请求跨太平洋到美西Agent 开始循环——调模型、查知识库、调工单系统 API、再调模型生成回复。这一圈下来光是网络往返就可能吃掉 800ms 到 1.5s还没算模型推理本身的时间。用户体感就是这 AI 怎么这么慢。第一个硬伤是延迟叠加。Agent 和普通 API 最大的区别在于它是多轮循环的。一次用户请求背后可能是 3 到 10 次模型调用加若干次工具调用每一次调用都是一次网络往返。中心化架构下这些往返全部要跨越长距离延迟是累加的不是平均的。第二个硬伤是状态管理的复杂度。Agent 需要记忆——对话历史、中间推理结果、工具返回的数据。中心化架构里这些状态存在数据库或者 Redis 里每次循环都要读写。并发一上来状态一致性和锁竞争就成了问题。你可能会说用无状态设计但 Agent 的记忆本质上就是有状态的硬做成无状态只会把复杂度转移到别处。第三个硬伤是成本结构。中心化意味着你要为峰值流量预留算力但 Agent 的流量往往是脉冲式的。闲时资源浪费忙时排队。而边缘计算的按请求计费模型理论上更贴合这种脉冲特征。2.2 边缘运行时的真实优势与它的代价Cloudflare Workers 这类边缘运行时的核心优势有三个地理就近代码跑在离用户最近的节点、极速冷启动V8 isolate 而非容器启动在毫秒级、全球一致的部署一次部署全球生效。这三点对 Agent 来说都是刚需。但代价也很明显而且很多人一开始会低估执行时间限制。Workers 的单次请求有 CPU 时间上限虽然可以通过 Durable Objects 或者 Queue 做长任务但你不能像在服务器上那样跑一个无限循环的 Agent。这逼着你把 Agent 循环设计成可中断、可恢复的。运行时限制。Workers 跑的是 V8 isolate不是 Node.js 完整环境。很多依赖原生模块的库用不了文件系统、长连接这些概念也不一样。状态是分布式的。边缘节点之间不共享内存你要么用 Durable Objects 做单点状态要么用 KV / D1 / R2 做持久化要么用 Durable Objects 的 Actor 模型做协调。这直接决定了你的 Agent 记忆架构怎么设计。提示如果你打算把现有的 Node.js Agent 项目直接搬到 Workers 上先别急着改代码先做一件事——把项目里所有依赖fs、net、原生模块的地方列出来。这一步能帮你提前判断迁移成本我见过太多人写到一半才发现某个关键库根本跑不起来。2.3 Gatekeepers这个词透露的架构信号关键词里有个Gatekeepers这个词很关键。在 Agent 系统里Gatekeeper 通常指的是在 Agent 执行关键动作前的拦截与校验层。比如 Agent 要调用一个会花钱的 API、要写数据库、要发邮件这些动作不能让它随便做得有个守门人来判断这个动作是否在授权范围内参数是否合法是否需要人工确认把 Gatekeeper 放在边缘侧有个天然的好处它离用户近能在请求进入核心系统之前就完成拦截。这既降低了核心系统的压力也提高了安全性——恶意或者越权的请求在边缘就被挡掉了根本到不了后端。这其实是cloudflare-os这类项目一个容易被忽略的价值点它不只是让 Agent 跑得快还让 Agent 跑得可控。3. 拆解 cloudflare-os 的核心技术栈Workers、Durable Objects 与 Agent 编排3.1 Workers 作为 Agent 的系统调用层如果把cloudflare-os类比成一个操作系统那 Cloudflare Workers 就是它的系统调用层。Agent 需要的能力——发起 HTTP 请求、读写存储、调用模型、调度定时任务——在 Workers 里都有对应的绑定binding。我实际用下来最常用的几个绑定是绑定类型用途在 Agent 里的典型场景KV键值存储读多写少存 Agent 配置、提示词模板、静态知识D1SQLite 数据库存对话历史、结构化记忆R2对象存储存大文件、向量数据、日志归档Durable Objects有状态协调对象Agent 会话状态、锁、计数器Queues异步消息队列长任务拆分、Agent 任务分发AI内置模型推理直接调模型不用自己接 API这张表不是让你背而是让你建立一个判断什么样的数据放什么地方。我见过有人把对话历史塞进 KV结果因为 KV 的最终一致性Agent 读到的历史是旧的导致回复错乱。对话历史这种强一致、频繁更新的数据应该放 D1 或者 Durable Objects。3.2 Durable ObjectsAgent 记忆与并发控制的关键Durable Objects简称 DO是这套架构里最容易被低估、也最值得深入理解的部分。它的核心特性是每个 DO 实例在全球只有一个所有请求都路由到同一个实例。这听起来像是回到了中心化但关键在于 DO 是按需激活、自动迁移的而且它提供的是强一致的单点协调能力。对 Agent 来说DO 解决了一个核心问题会话状态的一致性。一个用户的 Agent 会话可以绑定到一个 DO 实例。这个实例负责维护对话历史、当前任务状态、工具调用结果。因为所有请求都路由到同一个实例就不存在并发读写冲突的问题。// 一个简化的 Agent 会话 Durable Object 结构 export class AgentSession { constructor(state, env) { this.state state; this.env env; // 从持久化存储恢复会话状态 this.history []; } async fetch(request) { const { message } await request.json(); // 把用户消息加入历史 this.history.push({ role: user, content: message }); // 调用模型生成回复这里用 Workers AI 绑定 const response await this.env.AI.run(cf/meta/llama-3-8b-instruct, { messages: this.history }); this.history.push({ role: assistant, content: response.response }); // 持久化状态 await this.state.storage.put(history, this.history); return new Response(JSON.stringify({ reply: response.response })); } }这段代码是简化版但能说明 DO 的工作方式它把会话这个有状态的东西封装成一个对象所有操作都在这个对象内部串行执行。你不用担心两个请求同时修改历史导致数据错乱DO 帮你保证了串行性。注意DO 虽然强一致但它的吞吐是有限的。单个 DO 实例的请求是串行处理的如果你的 Agent 会话并发很高单个 DO 会成为瓶颈。实践中常见的做法是按用户或按会话分片每个用户一个 DO 实例这样并发就分散开了。3.3 Agent 编排把循环拆成可恢复的状态机前面提到 Workers 有执行时间限制所以 Agent 的思考-行动-观察循环不能写成一个大 while 循环。正确的做法是把它拆成状态机每一步都是一个独立的请求或者一个 Queue 消息。我自己的做法是这样的把 Agent 的一次完整任务拆成若干个步骤每个步骤执行完就把状态存进 DO然后决定下一步是继续、等待、还是结束。如果任务很长就用 Queue 把下一步丢进去异步执行。这样即使某个请求超时了状态还在可以从断点恢复。这种设计的好处不只是绕过时间限制更重要的是可观测。每一步都有明确的输入输出出问题的时候你能精确定位是哪一步错了而不是面对一个黑盒循环干瞪眼。4. 从零搭一个边缘 Agent我的实操路径与关键决策4.1 环境准备别急着写代码先把项目骨架搭对我建议用wrangler作为开发工具它是 Cloudflare 官方的 CLI。初始化项目的时候选择 TypeScript 模板因为 Agent 项目涉及大量数据结构类型系统能帮你省掉很多运行时错误。# 初始化项目 npm create cloudflarelatest my-agent-os -- --typehello-world --ts # 进入项目目录 cd my-agent-os # 安装常用依赖 npm install hono zod这里我选了hono作为 Web 框架而不是用原生的 fetch handler。原因是 Hono 的路由和中间件机制非常适合做 Gatekeeper 层——你可以在中间件里统一做鉴权、限流、参数校验代码比手写 if-else 清爽得多。zod用来做参数校验Agent 的工具调用参数必须严格校验否则很容易被注入奇怪的输入。wrangler.toml是配置文件你需要在这里声明各种绑定。我列一个典型的 Agent 项目配置name my-agent-os main src/index.ts compatibility_date 2024-09-23 [[durable_objects.bindings]] name AGENT_SESSION class_name AgentSession [[kv_namespaces]] binding AGENT_CONFIG id your-kv-id [[d1_databases]] binding AGENT_DB database_name agent-db database_id your-d1-id [[queues.producers]] binding TASK_QUEUE queue agent-tasks [ai] binding AI这个配置里每一项都有它的用途别嫌麻烦。我见过有人图省事把所有状态都塞进一个 KV结果后面想加事务、想加查询的时候发现根本做不了只能推倒重来。4.2 设计 Gatekeeper 层Agent 安全的第一道防线Gatekeeper 是我认为cloudflare-os这类项目最值得认真对待的部分。Agent 和普通程序最大的区别是它的行为是模型生成的你没法完全预测它会调用什么工具、传什么参数。所以必须有一层独立的校验逻辑在工具真正执行前拦截。我的 Gatekeeper 设计分三层第一层是身份与权限校验。每个请求进来先确认调用者是谁它有哪些权限。这一步用 Hono 中间件做把用户身份和权限挂到 context 上。第二层是工具白名单与参数校验。Agent 想调用某个工具Gatekeeper 先检查这个工具是否在允许列表里然后用 zod schema 校验参数。参数不合法直接拒绝不进入执行。第三层是敏感操作的人工确认。对于花钱、发消息、改数据这类不可逆操作Gatekeeper 可以挂起任务等人工确认后再继续。这一步用 DO 的状态机来实现任务状态标记为待确认确认后通过 Queue 重新触发。// Gatekeeper 中间件的简化实现 import { z } from zod; const toolSchemas { search_knowledge: z.object({ query: z.string().max(500), topK: z.number().int().min(1).max(10).default(3) }), send_email: z.object({ to: z.string().email(), subject: z.string().max(200), body: z.string().max(5000) }) }; async function gatekeeper(c, next) { const { tool, params } await c.req.json(); // 检查工具是否在白名单 if (!toolSchemas[tool]) { return c.json({ error: Tool not allowed }, 403); } // 校验参数 const result toolSchemas[tool].safeParse(params); if (!result.success) { return c.json({ error: Invalid params, details: result.error }, 400); } // 敏感操作需要人工确认 if (tool send_email) { // 挂起任务等待确认 return c.json({ status: pending_confirmation, taskId: ... }); } c.set(validatedParams, result.data); await next(); }这套设计的关键在于校验逻辑和业务逻辑分离。工具的实现者不需要关心权限和参数校验Gatekeeper 统一处理。这样加新工具的时候只需要在 schema 里加一条不用改业务代码。4.3 记忆架构短期、长期与向量记忆的分层Agent 的记忆不能一锅炖。我把它分成三层短期记忆是当前会话的对话历史存在 DO 里强一致读写频繁。这一层不需要持久化太久会话结束就可以归档。长期记忆是跨会话的用户偏好、历史事实存在 D1 里。这一层需要结构化查询比如这个用户上次提到过什么。向量记忆是语义检索用的把文本转成向量存起来需要的时候做相似度搜索。Cloudflare 有 Vectorize 服务可以配合 Workers AI 的 embedding 模型用。分层的意义在于成本和性能的平衡。短期记忆要快所以放 DO长期记忆要能查所以放 D1向量记忆要能语义匹配所以放 Vectorize。如果你把三者混在一起要么慢要么贵要么查不准。提示向量记忆最容易踩的坑是embedding 模型和检索时用的模型不一致。存的时候用 A 模型查的时候用 B 模型向量空间对不上检索结果全是乱的。这个坑我踩过一次排查了大半天才反应过来。5. 实测中的性能表现与那些文档不会告诉你的坑5.1 冷启动与延迟的真实数据我在实际测试中把同一个 Agent 分别部署在中心化服务器和 Workers 上做了对比。测试场景是简单的问答 Agent包含一次模型调用和一次知识库检索。指标中心化服务器美西Workers 边缘冷启动800ms - 2s接近 0ms首次响应亚洲用户1.2s - 2.5s300ms - 600ms并发 100 时 P953.5s1.1s空闲成本持续计费按请求计费这个数据不是说 Workers 全面碾压而是说在延迟敏感、流量脉冲的场景下边缘架构的优势非常明显。但如果你做的是批处理任务或者需要长时间运行的计算中心化服务器反而更合适。5.2 那些让我熬夜排查的坑坑一DO 的存储写入不是免费的。DO 的 storage 写入有延迟如果你在每次对话后都同步写一次高频对话下会明显拖慢响应。我的做法是批量写入攒几条再一起写或者用state.blockConcurrencyWhile控制写入时机。坑二Queue 的消息可能重复。Queue 保证的是至少一次投递不是恰好一次。所以你的任务处理逻辑必须幂等。我一开始没注意结果一个发邮件的任务被执行了两次用户收到两封一样的邮件非常尴尬。后来给每个任务加了唯一 ID处理前先检查是否已处理过。坑三Workers 的 CPU 时间限制比你想的严格。注意是 CPU 时间不是墙钟时间。等待网络请求的时间不算 CPU 时间但 JSON 解析、字符串处理、加密这些算。我有个任务因为处理一个超大 JSON 超过了 CPU 限制直接被 kill。解决办法是把大 JSON 的处理拆成多个小步骤或者用 Stream 处理。坑四本地开发环境和线上不一致。wrangler dev默认跑在本地很多绑定是模拟的。DO 的行为、Queue 的行为在本地和线上可能有差异。我建议尽早部署到线上测试别等到开发完了才发现线上跑不起来。5.3 成本控制的几个实用技巧边缘计算按请求计费听起来便宜但 Agent 的请求量可能很大。我总结了几个控制成本的技巧合并请求。Agent 的多步循环如果能合并成一次请求就合并。比如把多个工具调用打包成一个批量请求。缓存模型结果。相同的输入没必要重复调模型用 KV 做一层缓存命中率往往比你想的高。限制循环次数。Agent 的循环一定要有上限否则一个死循环能把你的账单跑爆。我一般设 10 步上限超过就报错。用便宜的模型做路由。不是所有请求都需要大模型。可以用小模型先做意图识别只有复杂请求才路由到大模型。6. 这套架构适合谁以及我对它的真实判断6.1 什么场景该用什么场景别硬上cloudflare-os这类边缘 Agent 架构最适合的场景是面向全球用户的、延迟敏感的、流量脉冲式的 Agent 应用。比如客服机器人、实时助手、轻量级工具调用 Agent。不适合的场景也很明确需要长时间计算、需要大量本地资源、依赖特定原生库的任务。比如视频处理、大规模数据分析、需要 GPU 密集推理的任务。这些场景硬搬到边缘只会给自己找麻烦。我的判断是边缘 Agent 不是要取代中心化架构而是补上了中心化架构在延迟和成本上的短板。一个成熟的系统往往是混合的边缘做接入、路由、轻量 Agent 循环中心做重计算、批处理、复杂编排。6.2 关于 Agent 安全我想多说两句关键词里agent安全是个高频词这不是偶然。Agent 越强大它能造成的破坏就越大。一个能调 API、能写数据库、能发消息的 Agent如果被恶意输入操控后果可能很严重。Gatekeeper 层是必须的但光有 Gatekeeper 不够。我的经验是还要加上输入净化防止提示词注入、输出审查防止 Agent 泄露敏感信息、行为审计记录 Agent 的每一步操作出问题能追溯。这三件事在边缘侧做成本低、效果好因为请求还没进入核心系统就被处理了。6.3 我踩过坑之后的一点体会最后分享一个我自己的体会。刚开始做边缘 Agent 的时候我总想着把功能做全什么记忆、什么多工具、什么复杂编排一股脑全上。结果系统复杂度爆炸调试困难性能也没达到预期。后来我换了个思路先把最小闭环跑通。一个 Agent一个工具一层记忆一个 Gatekeeper。跑通了再逐步加。这个思路听起来很朴素但在边缘这种限制多的环境里特别管用。因为每一步你都能清楚地知道是哪个环节出了问题而不是面对一个庞大的黑盒。边缘 Agent 这个方向我觉得还在很早期。cloudflare-os这个名字背后的野心可能比我们现在看到的要大。它想做的也许是把操作系统这个概念重新定义——从管理硬件到管理分布在全球的智能体。这个方向值不值得投入取决于你的场景。但至少理解它的架构思路对做任何 Agent 系统都有帮助。
