1. 从“cloudflare-os”这个标题说起它到底想解决什么问题第一次看到“cloudflare-os”这个标题很多人会误以为Cloudflare要发布一款桌面操作系统。其实不是。这里的“os”更接近“operating system for agents”的意思——一套让AI agent在云端边缘节点上稳定运行、协作、调度的运行时环境。它把Cloudflare Workers、Durable Objects、R2、KV、Queues这些原本分散的基础设施重新组织成一套面向agent的“操作系统层”。我最早接触这个方向是因为一个多agent协作的客服原型。当时用传统容器部署冷启动慢、状态同步麻烦、跨区域延迟高。后来把agent拆成Worker函数用Durable Objects做会话状态用Queues做任务分发整个链路才顺起来。这套思路其实就是“cloudflare-os”的雏形不追求通用OS的完整抽象而是针对agent的典型负载——短时高频调用、有状态会话、事件驱动、边缘就近执行——做最小化但够用的封装。它适合谁如果你正在做AI agent开发、多AI协作、agent记忆管理或者想用Rust、TypeScript写轻量agent并部署到边缘这套东西值得花时间研究。它不适合需要GPU密集推理的场景也不适合长时运行的重型任务。它的甜点区是I/O密集、状态轻量、需要全球低延迟响应的agent工作流。2. 核心架构拆解为什么是Workers Durable Objects Queues2.1 为什么不用传统容器跑agent传统容器跑agent有三个硬伤。第一冷启动。一个agent请求进来容器从零拉起可能要几百毫秒到几秒而agent交互往往要求首token延迟低于200ms。第二状态管理。agent需要记忆、会话上下文、工具调用中间态容器本身不提供跨请求的状态保持你得自己接Redis或数据库又多一跳网络。第三全球分布。容器通常部署在少数区域跨区域访问延迟不可控。Cloudflare Workers的模型正好补这三个洞。它在全球300多个节点运行冷启动接近零V8 isolate级别并且通过Durable Objects提供强一致的、可寻址的有状态对象。Queues则解决agent之间的异步任务传递。这三者组合起来就是一个天然的agent运行时。2.2 Durable Objects作为“agent记忆”的载体agent记忆分短期和长期。短期记忆是当前会话的上下文长期记忆是跨会话的用户偏好、历史摘要。Durable Objects适合做短期记忆每个会话一个DO实例所有消息按顺序进入DO内部用内存或事务存储维护状态。因为DO是单线程、强一致的不会出现并发写冲突。长期记忆我一般放R2或KV。R2存原始对话日志和向量化后的embeddingKV存用户画像的键值对。DO在会话结束时把摘要写入R2下次会话开始时从KV加载画像。这套组合实测下来比全放数据库要快因为DO到R2/KV的调用在同一网络内延迟很低。2.3 Queues在agent编排中的角色多agent协作时任务分发和结果回传需要可靠队列。比如一个“研究agent”拆出三个子任务给“搜索agent”“总结agent”“校验agent”用Queues做fan-out和fan-in。每个agent消费队列消息处理完再投递到下一个队列。Queues保证至少一次投递配合DO的幂等键可以做到精确一次效果。注意Queues的消息体有大小限制大文件或长文本不要直接塞队列传R2的key让消费者自己去取。3. 实操从零搭一个最小agent运行时3.1 环境准备与项目初始化你需要Node.js 18、Wrangler CLI、一个Cloudflare账号。初始化命令如下npm create cloudflarelatest cloudflare-os-demo cd cloudflare-os-demo npm install选择“Hello World Worker”模板语言选TypeScript。然后安装额外依赖npm install cloudflare/workers-types npm install -D wrangler在wrangler.toml里配置Durable Objects和Queues的绑定。一个典型配置长这样name cloudflare-os-demo main src/index.ts compatibility_date 2024-01-01 [[durable_objects.bindings]] name AGENT_SESSION class_name AgentSession [[queues.producers]] queue agent-tasks binding TASK_QUEUE [[queues.consumers]] queue agent-tasks max_batch_size 10 max_batch_timeout 5这里AgentSession是DO类名TASK_QUEUE是队列绑定名。max_batch_size和max_batch_timeout控制消费者一次拉多少消息、等多久。agent任务通常短小设10和5秒比较平衡。3.2 编写AgentSession Durable ObjectAgentSession负责维护单个会话的状态。核心逻辑是接收消息、追加到历史、调用模型、返回结果、更新状态。简化版代码如下export class AgentSession { state: DurableObjectState; history: Array{role: string, content: string} []; constructor(state: DurableObjectState) { this.state state; this.state.blockConcurrencyWhile(async () { this.history (await this.state.storage.get(history)) || []; }); } async fetch(request: Request) { const { message } await request.json(); this.history.push({ role: user, content: message }); const reply await this.callModel(this.history); this.history.push({ role: assistant, content: reply }); await this.state.storage.put(history, this.history); return new Response(JSON.stringify({ reply })); } async callModel(history: any[]) { // 这里调用你的模型API可以是外部服务 // 实际项目中建议用fetch调用并处理超时和重试 return 模拟回复; } }关键点blockConcurrencyWhile确保初始化完成前不处理请求每次fetch后持久化history防止DO被驱逐后丢状态。DO的存储有事务保证但不要每次消息都写可以攒几条再写减少存储操作次数。3.3 Worker入口与路由Worker入口负责把请求路由到对应的DO实例。用会话ID作为DO的keyexport default { async fetch(request: Request, env: Env) { const url new URL(request.url); const sessionId url.searchParams.get(session) || default; const id env.AGENT_SESSION.idFromName(sessionId); const stub env.AGENT_SESSION.get(id); return stub.fetch(request); } }这样同一个sessionId的请求总是打到同一个DO状态自然保持。不同用户用不同sessionId互不干扰。3.4 用Queues做多agent任务分发假设你有“搜索”和“总结”两个agent。Worker收到任务后投递到队列await env.TASK_QUEUE.send({ type: search, query: cloudflare-os agent, sessionId: user-123 });消费者Worker处理消息export default { async queue(batch: MessageBatchany, env: Env) { for (const msg of batch.messages) { const task msg.body; if (task.type search) { const result await doSearch(task.query); await env.TASK_QUEUE.send({ type: summarize, data: result, sessionId: task.sessionId }); } else if (task.type summarize) { const summary await doSummarize(task.data); // 把结果写回DO const id env.AGENT_SESSION.idFromName(task.sessionId); const stub env.AGENT_SESSION.get(id); await stub.fetch(new Request(https://internal/append, { method: POST, body: JSON.stringify({ role: assistant, content: summary }) })); } msg.ack(); } } }这里msg.ack()很重要处理成功才确认失败会自动重试。但要注意幂等同一个消息可能被投递多次DO的append操作要能识别重复。4. 常见问题与排查技巧实录4.1 DO并发写冲突怎么破DO本身是单线程的但如果你在DO内部用了异步操作比如fetch外部API在await期间可能有新请求进来。解决办法是用state.blockConcurrencyWhile包住关键段或者用DO的transactionAPI。我一般把“读-改-写”逻辑放在一个同步块里异步调用放在外面拿到结果后再进同步块更新。4.2 Queues消息重复消费Queues保证至少一次所以重复不可避免。每个任务带一个唯一taskIdDO里维护一个已处理taskId的集合可以用storage的set处理前先查处理后再记。集合大小要控制定期清理老ID。4.3 Worker冷启动真的零延迟吗V8 isolate冷启动确实很快但首次调用某个DO时DO需要从存储加载状态这个有延迟。优化方法是DO初始化时只加载必要字段历史消息分页加载不要一次性全读。另外DO有“hibernation”机制长时间无请求会休眠下次唤醒有轻微延迟。对延迟敏感的场景可以定期发心跳保持活跃。4.4 模型调用超时怎么办Worker的fetch有超时限制通常30秒到几分钟取决于计划。模型推理可能超过。解决办法把模型调用放到Queues里异步做Worker只负责接收和投递立即返回“处理中”。结果通过WebSocket或轮询回传。WebSocket可以用Durable Objects的WebSocket Hibernation API既保持连接又省资源。4.5 排查工具与日志Wrangler的wrangler tail可以实时看Worker日志。DO的日志也会输出到tail。Queues的消息可以在Dashboard里看积压和重试次数。我习惯在关键路径打结构化日志比如{event: agent_call, sessionId, latency}方便过滤。问题现象可能原因排查动作DO请求超时初始化加载大量数据检查storage.get是否一次读太多队列积压消费者处理慢或报错看tail日志检查ack时机状态丢失DO被驱逐且未持久化确认每次修改后调storage.put重复回复队列重复投递加taskId幂等检查跨区域延迟高DO位置固定用locationHint指定就近区域提示DO的locationHint可以在创建时指定比如idFromName后调stub.fetch时带cf: { locationHint: enam }让DO跑在离用户近的区域。5. 扩展玩法agent安全、多AI协作与Rust agent5.1 agent安全的基本防线agent安全不是单一措施而是分层。第一层输入过滤在Worker入口检查prompt注入特征比如“忽略之前指令”这类模式。第二层工具调用白名单agent能调用的外部API列在配置里不在白名单的直接拒绝。第三层输出审查模型返回后过一遍敏感词和格式校验。第四层权限隔离不同agent用不同DO命名空间不能互相访问存储。Durable Objects天然适合做权限边界因为每个DO实例是隔离的跨DO访问必须通过显式调用。你可以给每个agent一个DOagent之间通过Queues通信而不是直接共享状态。5.2 多AI协作的编排模式多AI协作常见三种模式串行、并行、辩论。串行是A的输出给BB给C。并行是A拆任务给B和C结果汇总给D。辩论是A和B各自出方案C做裁判。用Queues实现串行和并行很自然辩论模式需要DO维护一个共享的“辩论状态”每个agent的发言追加进去裁判agent读全部发言后裁决。我实测下来并行模式吞吐最高但结果一致性差串行模式可控但慢辩论模式质量最好但成本高。选择取决于场景客服适合串行研究适合并行决策支持适合辩论。5.3 用Rust写agent的可行性Cloudflare Workers支持Rust编译到WASM。用workers-rs可以写Rust agent。优势是性能好、内存安全适合计算密集的预处理比如文本分块、embedding计算。劣势是生态不如JS丰富很多SDK只有JS版。我的做法是核心逻辑用Rust写WASM模块编排和IO用TypeScript两者通过Worker的WASM绑定调用。use worker::*; #[event(fetch)] async fn main(req: Request, env: Env, _ctx: Context) - ResultResponse { let session_id req.url()?.query_pairs() .find(|(k, _)| k session) .map(|(_, v)| v.to_string()) .unwrap_or(default.into()); Response::ok(format!(session: {}, session_id)) }这个Rust Worker可以直接和JS的DO配合Rust Worker做入口把请求转发给DO。5.4 agent记忆的进阶设计短期记忆用DO长期记忆用R2向量库。向量库可以自己用DO实现一个简易版每个用户一个DO存embedding数组查询时算余弦相似度。数据量小的时候够用大了就迁到专门的向量服务。记忆的写入策略每轮对话后写短期每10轮或会话结束时做摘要写长期。摘要用一个小模型生成成本低。注意向量维度不要太高256或384足够高了存储和计算都吃不消。6. 我个人在实际操作中的几点体会这套东西我断断续续折腾了几个月踩过的坑比顺畅的时候多。最大的体会是不要试图把cloudflare-os当成万能运行时。它擅长的是“轻状态、高并发、全球分布”的agent场景。如果你的agent需要跑大模型推理、需要长时间计算、需要复杂的事务跨多个服务那还是老老实实用容器或专用推理服务。另一个体会是DO的存储操作要省着用。每次storage.put都是一次写有配额和成本。我一开始每条消息都写后来改成攒5条或每30秒写一次成本降了八成状态丢失风险也可接受。还有Queues的消费者要设好重试次数和死信队列不然一个坏消息会无限重试把配额耗光。最后agent安全别等到上线才想。我见过太多demo阶段随便跑上线后被prompt注入搞崩的例子。从第一天就把输入过滤、工具白名单、输出审查加上后面省心得多。这套cloudflare-os的思路本质上是用边缘基础设施的确定性去对冲AI agent的不确定性。基础设施稳了agent才能稳。 
长河君 · 2026/10/28 20:13:55 · 阅读 1.2k Cloudflare OS 实战：用 Workers 与 Durable Objects 构建边缘 AI Agent 运行时
1. 从“cloudflare-os”这个标题说起它到底想解决什么问题第一次看到“cloudflare-os”这个标题很多人会误以为Cloudflare要发布一款桌面操作系统。其实不是。这里的“os”更接近“operating system for agents”的意思——一套让AI agent在云端边缘节点上稳定运行、协作、调度的运行时环境。它把Cloudflare Workers、Durable Objects、R2、KV、Queues这些原本分散的基础设施重新组织成一套面向agent的“操作系统层”。我最早接触这个方向是因为一个多agent协作的客服原型。当时用传统容器部署冷启动慢、状态同步麻烦、跨区域延迟高。后来把agent拆成Worker函数用Durable Objects做会话状态用Queues做任务分发整个链路才顺起来。这套思路其实就是“cloudflare-os”的雏形不追求通用OS的完整抽象而是针对agent的典型负载——短时高频调用、有状态会话、事件驱动、边缘就近执行——做最小化但够用的封装。它适合谁如果你正在做AI agent开发、多AI协作、agent记忆管理或者想用Rust、TypeScript写轻量agent并部署到边缘这套东西值得花时间研究。它不适合需要GPU密集推理的场景也不适合长时运行的重型任务。它的甜点区是I/O密集、状态轻量、需要全球低延迟响应的agent工作流。2. 核心架构拆解为什么是Workers Durable Objects Queues2.1 为什么不用传统容器跑agent传统容器跑agent有三个硬伤。第一冷启动。一个agent请求进来容器从零拉起可能要几百毫秒到几秒而agent交互往往要求首token延迟低于200ms。第二状态管理。agent需要记忆、会话上下文、工具调用中间态容器本身不提供跨请求的状态保持你得自己接Redis或数据库又多一跳网络。第三全球分布。容器通常部署在少数区域跨区域访问延迟不可控。Cloudflare Workers的模型正好补这三个洞。它在全球300多个节点运行冷启动接近零V8 isolate级别并且通过Durable Objects提供强一致的、可寻址的有状态对象。Queues则解决agent之间的异步任务传递。这三者组合起来就是一个天然的agent运行时。2.2 Durable Objects作为“agent记忆”的载体agent记忆分短期和长期。短期记忆是当前会话的上下文长期记忆是跨会话的用户偏好、历史摘要。Durable Objects适合做短期记忆每个会话一个DO实例所有消息按顺序进入DO内部用内存或事务存储维护状态。因为DO是单线程、强一致的不会出现并发写冲突。长期记忆我一般放R2或KV。R2存原始对话日志和向量化后的embeddingKV存用户画像的键值对。DO在会话结束时把摘要写入R2下次会话开始时从KV加载画像。这套组合实测下来比全放数据库要快因为DO到R2/KV的调用在同一网络内延迟很低。2.3 Queues在agent编排中的角色多agent协作时任务分发和结果回传需要可靠队列。比如一个“研究agent”拆出三个子任务给“搜索agent”“总结agent”“校验agent”用Queues做fan-out和fan-in。每个agent消费队列消息处理完再投递到下一个队列。Queues保证至少一次投递配合DO的幂等键可以做到精确一次效果。注意Queues的消息体有大小限制大文件或长文本不要直接塞队列传R2的key让消费者自己去取。3. 实操从零搭一个最小agent运行时3.1 环境准备与项目初始化你需要Node.js 18、Wrangler CLI、一个Cloudflare账号。初始化命令如下npm create cloudflarelatest cloudflare-os-demo cd cloudflare-os-demo npm install选择“Hello World Worker”模板语言选TypeScript。然后安装额外依赖npm install cloudflare/workers-types npm install -D wrangler在wrangler.toml里配置Durable Objects和Queues的绑定。一个典型配置长这样name cloudflare-os-demo main src/index.ts compatibility_date 2024-01-01 [[durable_objects.bindings]] name AGENT_SESSION class_name AgentSession [[queues.producers]] queue agent-tasks binding TASK_QUEUE [[queues.consumers]] queue agent-tasks max_batch_size 10 max_batch_timeout 5这里AgentSession是DO类名TASK_QUEUE是队列绑定名。max_batch_size和max_batch_timeout控制消费者一次拉多少消息、等多久。agent任务通常短小设10和5秒比较平衡。3.2 编写AgentSession Durable ObjectAgentSession负责维护单个会话的状态。核心逻辑是接收消息、追加到历史、调用模型、返回结果、更新状态。简化版代码如下export class AgentSession { state: DurableObjectState; history: Array{role: string, content: string} []; constructor(state: DurableObjectState) { this.state state; this.state.blockConcurrencyWhile(async () { this.history (await this.state.storage.get(history)) || []; }); } async fetch(request: Request) { const { message } await request.json(); this.history.push({ role: user, content: message }); const reply await this.callModel(this.history); this.history.push({ role: assistant, content: reply }); await this.state.storage.put(history, this.history); return new Response(JSON.stringify({ reply })); } async callModel(history: any[]) { // 这里调用你的模型API可以是外部服务 // 实际项目中建议用fetch调用并处理超时和重试 return 模拟回复; } }关键点blockConcurrencyWhile确保初始化完成前不处理请求每次fetch后持久化history防止DO被驱逐后丢状态。DO的存储有事务保证但不要每次消息都写可以攒几条再写减少存储操作次数。3.3 Worker入口与路由Worker入口负责把请求路由到对应的DO实例。用会话ID作为DO的keyexport default { async fetch(request: Request, env: Env) { const url new URL(request.url); const sessionId url.searchParams.get(session) || default; const id env.AGENT_SESSION.idFromName(sessionId); const stub env.AGENT_SESSION.get(id); return stub.fetch(request); } }这样同一个sessionId的请求总是打到同一个DO状态自然保持。不同用户用不同sessionId互不干扰。3.4 用Queues做多agent任务分发假设你有“搜索”和“总结”两个agent。Worker收到任务后投递到队列await env.TASK_QUEUE.send({ type: search, query: cloudflare-os agent, sessionId: user-123 });消费者Worker处理消息export default { async queue(batch: MessageBatchany, env: Env) { for (const msg of batch.messages) { const task msg.body; if (task.type search) { const result await doSearch(task.query); await env.TASK_QUEUE.send({ type: summarize, data: result, sessionId: task.sessionId }); } else if (task.type summarize) { const summary await doSummarize(task.data); // 把结果写回DO const id env.AGENT_SESSION.idFromName(task.sessionId); const stub env.AGENT_SESSION.get(id); await stub.fetch(new Request(https://internal/append, { method: POST, body: JSON.stringify({ role: assistant, content: summary }) })); } msg.ack(); } } }这里msg.ack()很重要处理成功才确认失败会自动重试。但要注意幂等同一个消息可能被投递多次DO的append操作要能识别重复。4. 常见问题与排查技巧实录4.1 DO并发写冲突怎么破DO本身是单线程的但如果你在DO内部用了异步操作比如fetch外部API在await期间可能有新请求进来。解决办法是用state.blockConcurrencyWhile包住关键段或者用DO的transactionAPI。我一般把“读-改-写”逻辑放在一个同步块里异步调用放在外面拿到结果后再进同步块更新。4.2 Queues消息重复消费Queues保证至少一次所以重复不可避免。每个任务带一个唯一taskIdDO里维护一个已处理taskId的集合可以用storage的set处理前先查处理后再记。集合大小要控制定期清理老ID。4.3 Worker冷启动真的零延迟吗V8 isolate冷启动确实很快但首次调用某个DO时DO需要从存储加载状态这个有延迟。优化方法是DO初始化时只加载必要字段历史消息分页加载不要一次性全读。另外DO有“hibernation”机制长时间无请求会休眠下次唤醒有轻微延迟。对延迟敏感的场景可以定期发心跳保持活跃。4.4 模型调用超时怎么办Worker的fetch有超时限制通常30秒到几分钟取决于计划。模型推理可能超过。解决办法把模型调用放到Queues里异步做Worker只负责接收和投递立即返回“处理中”。结果通过WebSocket或轮询回传。WebSocket可以用Durable Objects的WebSocket Hibernation API既保持连接又省资源。4.5 排查工具与日志Wrangler的wrangler tail可以实时看Worker日志。DO的日志也会输出到tail。Queues的消息可以在Dashboard里看积压和重试次数。我习惯在关键路径打结构化日志比如{event: agent_call, sessionId, latency}方便过滤。问题现象可能原因排查动作DO请求超时初始化加载大量数据检查storage.get是否一次读太多队列积压消费者处理慢或报错看tail日志检查ack时机状态丢失DO被驱逐且未持久化确认每次修改后调storage.put重复回复队列重复投递加taskId幂等检查跨区域延迟高DO位置固定用locationHint指定就近区域提示DO的locationHint可以在创建时指定比如idFromName后调stub.fetch时带cf: { locationHint: enam }让DO跑在离用户近的区域。5. 扩展玩法agent安全、多AI协作与Rust agent5.1 agent安全的基本防线agent安全不是单一措施而是分层。第一层输入过滤在Worker入口检查prompt注入特征比如“忽略之前指令”这类模式。第二层工具调用白名单agent能调用的外部API列在配置里不在白名单的直接拒绝。第三层输出审查模型返回后过一遍敏感词和格式校验。第四层权限隔离不同agent用不同DO命名空间不能互相访问存储。Durable Objects天然适合做权限边界因为每个DO实例是隔离的跨DO访问必须通过显式调用。你可以给每个agent一个DOagent之间通过Queues通信而不是直接共享状态。5.2 多AI协作的编排模式多AI协作常见三种模式串行、并行、辩论。串行是A的输出给BB给C。并行是A拆任务给B和C结果汇总给D。辩论是A和B各自出方案C做裁判。用Queues实现串行和并行很自然辩论模式需要DO维护一个共享的“辩论状态”每个agent的发言追加进去裁判agent读全部发言后裁决。我实测下来并行模式吞吐最高但结果一致性差串行模式可控但慢辩论模式质量最好但成本高。选择取决于场景客服适合串行研究适合并行决策支持适合辩论。5.3 用Rust写agent的可行性Cloudflare Workers支持Rust编译到WASM。用workers-rs可以写Rust agent。优势是性能好、内存安全适合计算密集的预处理比如文本分块、embedding计算。劣势是生态不如JS丰富很多SDK只有JS版。我的做法是核心逻辑用Rust写WASM模块编排和IO用TypeScript两者通过Worker的WASM绑定调用。use worker::*; #[event(fetch)] async fn main(req: Request, env: Env, _ctx: Context) - ResultResponse { let session_id req.url()?.query_pairs() .find(|(k, _)| k session) .map(|(_, v)| v.to_string()) .unwrap_or(default.into()); Response::ok(format!(session: {}, session_id)) }这个Rust Worker可以直接和JS的DO配合Rust Worker做入口把请求转发给DO。5.4 agent记忆的进阶设计短期记忆用DO长期记忆用R2向量库。向量库可以自己用DO实现一个简易版每个用户一个DO存embedding数组查询时算余弦相似度。数据量小的时候够用大了就迁到专门的向量服务。记忆的写入策略每轮对话后写短期每10轮或会话结束时做摘要写长期。摘要用一个小模型生成成本低。注意向量维度不要太高256或384足够高了存储和计算都吃不消。6. 我个人在实际操作中的几点体会这套东西我断断续续折腾了几个月踩过的坑比顺畅的时候多。最大的体会是不要试图把cloudflare-os当成万能运行时。它擅长的是“轻状态、高并发、全球分布”的agent场景。如果你的agent需要跑大模型推理、需要长时间计算、需要复杂的事务跨多个服务那还是老老实实用容器或专用推理服务。另一个体会是DO的存储操作要省着用。每次storage.put都是一次写有配额和成本。我一开始每条消息都写后来改成攒5条或每30秒写一次成本降了八成状态丢失风险也可接受。还有Queues的消费者要设好重试次数和死信队列不然一个坏消息会无限重试把配额耗光。最后agent安全别等到上线才想。我见过太多demo阶段随便跑上线后被prompt注入搞崩的例子。从第一天就把输入过滤、工具白名单、输出审查加上后面省心得多。这套cloudflare-os的思路本质上是用边缘基础设施的确定性去对冲AI agent的不确定性。基础设施稳了agent才能稳。