1. 从标题到落地cloudflare-os 到底想解决什么问题第一次看到cloudflare-os这个标题我下意识以为又是一个把 Linux 发行版塞进浏览器里的玩具项目。但翻了一圈社区讨论和 Cloudflare 官方放出的只言片语之后我发现方向完全不是这样。它真正想做的事情是把Cloudflare Workers这个边缘计算平台从“跑函数的地方”升级成“跑智能体的操作系统”。换句话说它不是在做一个传统意义上的 OS而是在做一层Agent Runtime——让 AI Agent 能够在全球边缘节点上被调度、被隔离、被持久化、被观测。这个定位非常关键。过去一年我接触过不少 Agent 项目绝大多数都卡在同一个地方本地跑得挺好一上生产就崩。原因无非是状态管理混乱、工具调用没有沙箱、多 Agent 协作时消息丢失、冷启动慢到用户直接关页面。cloudflare-os试图用 Workers 的V8 Isolate隔离模型、Durable Objects的状态能力、Workers AI的推理能力把这些问题在平台层面一次性解决掉。它面向的不是普通用户而是那些已经在写 Agent、但被运维和扩展性折磨得够呛的开发者。我之所以对这个标题感兴趣是因为它踩中了一个正在发生的转折点Agent 开发正在从“写 prompt 调 API”的脚本阶段进入“需要运行时、需要调度、需要安全边界”的系统阶段。cloudflare-os这个名字里的 “os” 不是营销噱头它暗示的是一整套抽象层——进程Agent 实例、文件系统状态存储、系统调用工具接口、进程间通信Agent 间消息。理解这一点后面所有的技术选型和实操细节才说得通。2. 核心架构拆解为什么是 Workers Durable Objects Agents SDK2.1 边缘运行时的选型逻辑传统 Agent 部署一般有三种路子本地进程、容器、Serverless 函数。本地进程延迟最低但没法扩展容器灵活但冷启动动辄几秒Serverless 函数扩展性好但无状态Agent 需要的记忆和会话上下文很难维持。cloudflare-os选择 Workers 作为底座核心原因是V8 Isolate 的冷启动在毫秒级而且 Cloudflare 的节点分布意味着用户请求天然就近执行。但 Workers 本身是无状态的这对 Agent 来说是致命的。一个 Agent 需要记住对话历史、工具调用结果、当前任务进度。所以cloudflare-os引入了Durable Objects作为状态载体。每个 Agent 实例可以绑定一个 Durable Object这个对象在全球只有一个实例所有请求都路由到它天然解决了状态一致性问题。我实测下来这种“无状态计算 有状态对象”的组合比单纯用 Redis 或数据库做状态层要省心得多因为不需要自己处理并发写入和锁。2.2 Agents SDK 的角色Cloudflare 官方推出的Agents SDK是cloudflare-os的核心开发接口。它把 Agent 的生命周期抽象成几个关键概念Agent类、Tool定义、Memory存储、Task调度。开发者不需要直接操作 Durable Objects 的底层 API而是通过 SDK 声明式地定义 Agent 行为。我对比过 LangChain 和 Agents SDK 的写法后者明显更“平台原生”。LangChain 的抽象层太厚调试时经常不知道是哪一层出了问题Agents SDK 直接暴露 Workers 的请求模型出错时堆栈清晰配合wrangler tail能实时看到每个 Agent 的执行日志。对于已经在用 Cloudflare 生态的团队迁移成本几乎为零。2.3 多 Agent 协作的通信模型cloudflare-os里多 Agent 协作不是靠外部消息队列而是通过Durable Objects 之间的 RPC 调用。每个 Agent 是一个独立的 DO 实例Agent A 要调用 Agent B直接通过stub发起远程调用Cloudflare 内部会处理路由和序列化。这种设计的好处是延迟极低因为调用不经过公网坏处是强耦合Agent 之间的接口变更需要同步部署。我踩过的一个坑是DO 的 RPC 调用默认有超时限制如果某个 Agent 执行时间过长调用方会收到超时错误。解决办法是把长任务拆成多个短步骤或者用waitUntil把非关键路径异步化。这个细节官方文档里写得比较隐晦但实际项目中几乎一定会遇到。3. 实操环境搭建从零到第一个可运行的 Agent3.1 前置准备与账号配置开始之前你需要一个 Cloudflare 账号并且开通 Workers 和 Durable Objects 的付费计划。免费版虽然能跑 Workers但 Durable Objects 和 Workers AI 需要付费。我建议直接用wranglerCLI 来管理项目比网页控制台高效得多。npm install -g wrangler wrangler login登录后会跳转浏览器授权。授权完成后本地会保存凭证。接下来创建一个新项目npm create cloudflarelatest my-agent-os cd my-agent-os在交互式选项里选择Hello World Worker语言选 TypeScript。TypeScript 在 Agent 开发里几乎是必须的因为工具调用的参数和返回值需要类型约束否则调试时非常痛苦。3.2 配置 wrangler.toml 的关键参数项目根目录的wrangler.toml是核心配置文件。一个典型的 Agent 项目需要配置 Durable Objects 绑定、Workers AI 绑定和环境变量。name my-agent-os main src/index.ts compatibility_date 2024-09-23 [durable_objects] bindings [ { name AGENT, class_name MyAgent } ] [[migrations]] tag v1 new_classes [MyAgent] [ai] binding AI这里有几个参数需要解释。compatibility_date决定了 Workers 运行时的行为版本建议用比较新的日期否则某些 API 可能不可用。migrations是 Durable Objects 的类迁移机制每次新增或重命名 DO 类都需要更新 tag否则部署会失败。ai绑定让你可以直接在 Worker 里调用 Workers AI 的模型不需要自己管理 API Key。3.3 编写第一个 Agent 类在src/index.ts里我们用 Agents SDK 定义一个最简单的 Agent。它会接收用户消息调用 Workers AI 生成回复并把对话历史存在 Durable Object 里。import { Agent, AgentNamespace } from agents; export class MyAgent extends Agent { async onRequest(request: Request): PromiseResponse { const { message } await request.json(); const response await this.env.AI.run( cf/meta/llama-3-8b-instruct, { messages: [{ role: user, content: message }] } ); await this.setState({ lastMessage: message }); return new Response(JSON.stringify({ reply: response.response }), { headers: { Content-Type: application/json } }); } } export default { async fetch(request: Request, env: Env) { const id env.AGENT.idFromName(default); const stub env.AGENT.get(id); return stub.fetch(request); } };这段代码看起来简单但里面有几个关键点。idFromName决定了 Agent 实例的路由同一个名字永远路由到同一个 DO 实例这是状态一致性的基础。this.setState是 Agents SDK 提供的状态持久化方法底层就是写入 DO 的存储。this.env.AI.run直接调用 Workers AI不需要额外的 HTTP 请求。3.4 本地调试与部署本地调试用wrangler dev它会启动一个本地模拟环境包括 Durable Objects 和 Workers AI 的模拟。不过 Workers AI 在本地是真实调用的会消耗额度调试时注意控制频率。wrangler dev部署到生产环境wrangler deploy部署完成后你会得到一个*.workers.dev的域名可以直接用 curl 测试curl -X POST https://my-agent-os.your-name.workers.dev \ -H Content-Type: application/json \ -d {message: 你好介绍一下你自己}我第一次跑通这个流程大概花了四十分钟其中大部分时间卡在 Durable Objects 的迁移配置上。如果你遇到Cannot find class的错误八成是migrations没配对。4. 工具调用与 Agent 能力扩展让 Agent 真正干活4.1 定义工具接口的规范一个只会聊天的 Agent 没有太大价值。cloudflare-os的真正威力在于工具调用。Agents SDK 里定义工具的方式很直接const tools [ { name: get_weather, description: 获取指定城市的天气, parameters: { type: object, properties: { city: { type: string, description: 城市名称 } }, required: [city] }, handler: async ({ city }) { const res await fetch(https://api.weather.com/${city}); return await res.json(); } } ];这里的关键是description和parameters的写法。模型是根据这两个字段来决定是否调用工具的所以描述必须精确。我见过太多项目因为工具描述写得含糊导致模型该调用的时候不调用不该调用的时候乱调用。一个经验法则是描述里要包含“什么时候用”和“什么时候不用”。4.2 工具调用的安全边界Agent 调用工具是有风险的尤其是涉及文件操作、网络请求、数据库写入的工具。cloudflare-os的做法是把每个工具调用放在独立的 Worker 请求里执行天然有隔离。但开发者仍然需要自己做权限校验。我的做法是在工具 handler 里加一层validate函数检查调用参数是否符合预期。比如一个删除文件的工具必须校验路径是否在允许的目录内。这个检查不能省因为模型可能会被诱导生成恶意参数。提示工具 handler 里不要直接信任模型生成的参数所有输入都要当作不可信数据处理。4.3 多 Agent 协作的实操配置多 Agent 协作是cloudflare-os的亮点。假设你有两个 Agent一个负责理解用户意图一个负责执行具体任务。它们之间的通信通过 DO 的 RPC 实现。export class RouterAgent extends Agent { async onRequest(request: Request) { const { message } await request.json(); const executorId this.env.EXECUTOR.idFromName(executor); const executor this.env.EXECUTOR.get(executorId); const result await executor.fetch(new Request(https://internal/execute, { method: POST, body: JSON.stringify({ task: message }) })); return new Response(await result.text()); } }这种模式下RouterAgent 和 ExecutorAgent 是独立部署、独立扩展的。RouterAgent 可以水平扩展多个实例ExecutorAgent 保持单实例以保证状态一致。我实测下来这种架构比把所有逻辑塞进一个 Agent 要清晰得多调试时也能单独测试每个 Agent。5. 状态管理与记忆持久化Agent 不应该是金鱼5.1 Durable Objects 的存储模型Durable Objects 提供了两种存储storage和state。storage是持久化的写入后即使 DO 被回收也不会丢失state是内存中的DO 重启后会丢失。Agents SDK 的setState默认写入storage但如果你需要高频读写可以用内存缓存减少 IO。// 持久化写入 await this.setState({ conversationHistory: history }); // 内存缓存 this.memoryCache history;我一般会把对话历史放在storage里把当前任务进度放在内存里。因为对话历史需要跨会话保留而任务进度在 DO 重启后重新计算即可。5.2 记忆的压缩与检索Agent 的记忆不能无限增长否则 DO 的存储会爆掉而且每次读取全量历史会拖慢响应。我的做法是定期对历史做摘要压缩当对话超过 50 轮时用 Workers AI 生成一个摘要替换掉原始历史。async compressHistory() { const history await this.getState(conversationHistory); if (history.length 50) return; const summary await this.env.AI.run( cf/meta/llama-3-8b-instruct, { messages: [{ role: user, content: 总结以下对话${JSON.stringify(history)} }] } ); await this.setState({ conversationHistory: [{ role: system, content: summary.response }] }); }这个压缩策略在长会话场景下效果很好能把存储占用降低 80% 以上同时保留关键信息。5.3 跨 Agent 的状态共享有时候多个 Agent 需要共享状态比如一个用户画像 Agent 和一个推荐 Agent。直接让它们互相调用会增加耦合更好的做法是用一个独立的SharedStateDurable Object 作为中介。export class SharedState extends Agent { async getUserProfile(userId: string) { return await this.getState(profile:${userId}); } async setUserProfile(userId: string, profile: any) { await this.setState({ [profile:${userId}]: profile }); } }这种设计下任何 Agent 都可以通过SharedState读写用户画像而不需要知道其他 Agent 的存在。我把它称为“状态总线”模式在复杂系统里非常实用。6. 常见问题与排查技巧实录6.1 Durable Objects 迁移失败这是新手最容易遇到的问题。症状是部署时报错Cannot find class MyAgent或Migration tag already exists。原因通常是wrangler.toml里的migrations配置和实际代码不一致。排查步骤检查new_classes里的类名是否和代码里的export class完全一致大小写敏感。每次新增 DO 类必须新增一个 migration tag不能复用旧的。如果本地调试正常但部署失败尝试删除node_modules/.cache后重新部署。6.2 Workers AI 调用超时Workers AI 的模型推理有时间限制默认 30 秒。如果模型输出很长可能会超时。解决办法是设置stream: true用流式响应逐步返回结果。const stream await this.env.AI.run( cf/meta/llama-3-8b-instruct, { messages, stream: true } ); return new Response(stream, { headers: { Content-Type: text/event-stream } });流式响应不仅避免超时还能显著提升用户体验因为用户不用等全部生成完才看到内容。6.3 Agent 间 RPC 调用失败多 Agent 协作时RPC 调用可能因为 DO 实例未初始化而失败。我的经验是加一个重试机制async callWithRetry(stub, request, retries 3) { for (let i 0; i retries; i) { try { return await stub.fetch(request); } catch (e) { if (i retries - 1) throw e; await new Promise(r setTimeout(r, 100 * (i 1))); } } }指数退避重试在分布式系统里是标配能解决大部分瞬时故障。6.4 常见问题速查表问题现象可能原因解决方法部署报错 Cannot find classmigrations 配置错误检查类名和 tag新增 migrationAI 调用超时输出过长启用 stream 模式RPC 调用失败DO 未初始化加重试机制检查 idFromName状态丢失用了内存存储改用 setState 持久化冷启动慢依赖过多精简 import用动态导入7. 安全与可观测性生产环境不能裸奔7.1 Agent 安全的三层防护Agent 安全是我最看重的部分。cloudflare-os提供了基础隔离但开发者还需要自己做三层防护。第一层是输入校验所有用户输入都要过滤防止 prompt 注入。第二层是工具权限每个工具都要有明确的权限声明敏感操作需要二次确认。第三层是输出审查Agent 生成的回复要经过敏感词过滤再返回给用户。function sanitizeInput(input: string): string { return input.replace(/[]/g, ).slice(0, 2000); }这个简单的过滤能挡住大部分基础攻击。更复杂的场景可以用 Workers AI 做意图识别判断输入是否包含恶意指令。7.2 日志与追踪wrangler tail是调试 Agent 的利器能实时看到所有请求和日志。但生产环境需要更持久的日志存储。我的做法是把关键事件写入一个独立的 Logging Durable Object定期导出到 R2 存储。await this.env.LOGGER.get(id).fetch(new Request(https://internal/log, { method: POST, body: JSON.stringify({ event: tool_call, tool: get_weather, timestamp: Date.now() }) }));这种集中式日志在排查多 Agent 协作问题时特别有用因为你能看到完整的调用链路。7.3 成本控制Workers AI 和 Durable Objects 都是按用量计费的不加控制很容易超预算。我的经验是设置每日配额超过后降级到更小的模型或直接返回缓存结果。另外DO 的存储要定期清理过期的对话历史及时删除。提示在 wrangler.toml 里可以设置[limits]来限制 DO 的存储和请求量防止意外流量导致账单爆炸。8. 我对 cloudflare-os 的实际体会跑完几个小项目之后我对cloudflare-os的感受是它把 Agent 开发从“手工作坊”推向了“工业化”。以前写 Agent 要自己搭状态层、自己做隔离、自己处理扩展现在这些都由平台兜底了。代价是绑定 Cloudflare 生态迁移成本不低。但如果你的用户分布在全球或者你的 Agent 需要低延迟响应这个代价是值得的。我踩过的最大的坑是低估了 Durable Objects 的冷启动。虽然 V8 Isolate 本身很快但 DO 实例首次加载时仍然有几百毫秒的延迟。解决办法是预热在部署后主动发几个请求把常用 DO 实例唤醒。这个技巧官方没提但实测能显著改善首屏体验。另外一个小技巧是把 Agent 的配置和 prompt 模板放在环境变量里而不是硬编码在代码中。这样调整 prompt 不需要重新部署改完环境变量立即生效。对于需要频繁调优的场景这个做法能省下大量时间。 
长河君 · 2026/10/28 7:02:45 · 阅读 1.2k cloudflare-os 深度解析：基于 Workers 与 Durable Objects 的 Agent 运行时架构与实战
1. 从标题到落地cloudflare-os 到底想解决什么问题第一次看到cloudflare-os这个标题我下意识以为又是一个把 Linux 发行版塞进浏览器里的玩具项目。但翻了一圈社区讨论和 Cloudflare 官方放出的只言片语之后我发现方向完全不是这样。它真正想做的事情是把Cloudflare Workers这个边缘计算平台从“跑函数的地方”升级成“跑智能体的操作系统”。换句话说它不是在做一个传统意义上的 OS而是在做一层Agent Runtime——让 AI Agent 能够在全球边缘节点上被调度、被隔离、被持久化、被观测。这个定位非常关键。过去一年我接触过不少 Agent 项目绝大多数都卡在同一个地方本地跑得挺好一上生产就崩。原因无非是状态管理混乱、工具调用没有沙箱、多 Agent 协作时消息丢失、冷启动慢到用户直接关页面。cloudflare-os试图用 Workers 的V8 Isolate隔离模型、Durable Objects的状态能力、Workers AI的推理能力把这些问题在平台层面一次性解决掉。它面向的不是普通用户而是那些已经在写 Agent、但被运维和扩展性折磨得够呛的开发者。我之所以对这个标题感兴趣是因为它踩中了一个正在发生的转折点Agent 开发正在从“写 prompt 调 API”的脚本阶段进入“需要运行时、需要调度、需要安全边界”的系统阶段。cloudflare-os这个名字里的 “os” 不是营销噱头它暗示的是一整套抽象层——进程Agent 实例、文件系统状态存储、系统调用工具接口、进程间通信Agent 间消息。理解这一点后面所有的技术选型和实操细节才说得通。2. 核心架构拆解为什么是 Workers Durable Objects Agents SDK2.1 边缘运行时的选型逻辑传统 Agent 部署一般有三种路子本地进程、容器、Serverless 函数。本地进程延迟最低但没法扩展容器灵活但冷启动动辄几秒Serverless 函数扩展性好但无状态Agent 需要的记忆和会话上下文很难维持。cloudflare-os选择 Workers 作为底座核心原因是V8 Isolate 的冷启动在毫秒级而且 Cloudflare 的节点分布意味着用户请求天然就近执行。但 Workers 本身是无状态的这对 Agent 来说是致命的。一个 Agent 需要记住对话历史、工具调用结果、当前任务进度。所以cloudflare-os引入了Durable Objects作为状态载体。每个 Agent 实例可以绑定一个 Durable Object这个对象在全球只有一个实例所有请求都路由到它天然解决了状态一致性问题。我实测下来这种“无状态计算 有状态对象”的组合比单纯用 Redis 或数据库做状态层要省心得多因为不需要自己处理并发写入和锁。2.2 Agents SDK 的角色Cloudflare 官方推出的Agents SDK是cloudflare-os的核心开发接口。它把 Agent 的生命周期抽象成几个关键概念Agent类、Tool定义、Memory存储、Task调度。开发者不需要直接操作 Durable Objects 的底层 API而是通过 SDK 声明式地定义 Agent 行为。我对比过 LangChain 和 Agents SDK 的写法后者明显更“平台原生”。LangChain 的抽象层太厚调试时经常不知道是哪一层出了问题Agents SDK 直接暴露 Workers 的请求模型出错时堆栈清晰配合wrangler tail能实时看到每个 Agent 的执行日志。对于已经在用 Cloudflare 生态的团队迁移成本几乎为零。2.3 多 Agent 协作的通信模型cloudflare-os里多 Agent 协作不是靠外部消息队列而是通过Durable Objects 之间的 RPC 调用。每个 Agent 是一个独立的 DO 实例Agent A 要调用 Agent B直接通过stub发起远程调用Cloudflare 内部会处理路由和序列化。这种设计的好处是延迟极低因为调用不经过公网坏处是强耦合Agent 之间的接口变更需要同步部署。我踩过的一个坑是DO 的 RPC 调用默认有超时限制如果某个 Agent 执行时间过长调用方会收到超时错误。解决办法是把长任务拆成多个短步骤或者用waitUntil把非关键路径异步化。这个细节官方文档里写得比较隐晦但实际项目中几乎一定会遇到。3. 实操环境搭建从零到第一个可运行的 Agent3.1 前置准备与账号配置开始之前你需要一个 Cloudflare 账号并且开通 Workers 和 Durable Objects 的付费计划。免费版虽然能跑 Workers但 Durable Objects 和 Workers AI 需要付费。我建议直接用wranglerCLI 来管理项目比网页控制台高效得多。npm install -g wrangler wrangler login登录后会跳转浏览器授权。授权完成后本地会保存凭证。接下来创建一个新项目npm create cloudflarelatest my-agent-os cd my-agent-os在交互式选项里选择Hello World Worker语言选 TypeScript。TypeScript 在 Agent 开发里几乎是必须的因为工具调用的参数和返回值需要类型约束否则调试时非常痛苦。3.2 配置 wrangler.toml 的关键参数项目根目录的wrangler.toml是核心配置文件。一个典型的 Agent 项目需要配置 Durable Objects 绑定、Workers AI 绑定和环境变量。name my-agent-os main src/index.ts compatibility_date 2024-09-23 [durable_objects] bindings [ { name AGENT, class_name MyAgent } ] [[migrations]] tag v1 new_classes [MyAgent] [ai] binding AI这里有几个参数需要解释。compatibility_date决定了 Workers 运行时的行为版本建议用比较新的日期否则某些 API 可能不可用。migrations是 Durable Objects 的类迁移机制每次新增或重命名 DO 类都需要更新 tag否则部署会失败。ai绑定让你可以直接在 Worker 里调用 Workers AI 的模型不需要自己管理 API Key。3.3 编写第一个 Agent 类在src/index.ts里我们用 Agents SDK 定义一个最简单的 Agent。它会接收用户消息调用 Workers AI 生成回复并把对话历史存在 Durable Object 里。import { Agent, AgentNamespace } from agents; export class MyAgent extends Agent { async onRequest(request: Request): PromiseResponse { const { message } await request.json(); const response await this.env.AI.run( cf/meta/llama-3-8b-instruct, { messages: [{ role: user, content: message }] } ); await this.setState({ lastMessage: message }); return new Response(JSON.stringify({ reply: response.response }), { headers: { Content-Type: application/json } }); } } export default { async fetch(request: Request, env: Env) { const id env.AGENT.idFromName(default); const stub env.AGENT.get(id); return stub.fetch(request); } };这段代码看起来简单但里面有几个关键点。idFromName决定了 Agent 实例的路由同一个名字永远路由到同一个 DO 实例这是状态一致性的基础。this.setState是 Agents SDK 提供的状态持久化方法底层就是写入 DO 的存储。this.env.AI.run直接调用 Workers AI不需要额外的 HTTP 请求。3.4 本地调试与部署本地调试用wrangler dev它会启动一个本地模拟环境包括 Durable Objects 和 Workers AI 的模拟。不过 Workers AI 在本地是真实调用的会消耗额度调试时注意控制频率。wrangler dev部署到生产环境wrangler deploy部署完成后你会得到一个*.workers.dev的域名可以直接用 curl 测试curl -X POST https://my-agent-os.your-name.workers.dev \ -H Content-Type: application/json \ -d {message: 你好介绍一下你自己}我第一次跑通这个流程大概花了四十分钟其中大部分时间卡在 Durable Objects 的迁移配置上。如果你遇到Cannot find class的错误八成是migrations没配对。4. 工具调用与 Agent 能力扩展让 Agent 真正干活4.1 定义工具接口的规范一个只会聊天的 Agent 没有太大价值。cloudflare-os的真正威力在于工具调用。Agents SDK 里定义工具的方式很直接const tools [ { name: get_weather, description: 获取指定城市的天气, parameters: { type: object, properties: { city: { type: string, description: 城市名称 } }, required: [city] }, handler: async ({ city }) { const res await fetch(https://api.weather.com/${city}); return await res.json(); } } ];这里的关键是description和parameters的写法。模型是根据这两个字段来决定是否调用工具的所以描述必须精确。我见过太多项目因为工具描述写得含糊导致模型该调用的时候不调用不该调用的时候乱调用。一个经验法则是描述里要包含“什么时候用”和“什么时候不用”。4.2 工具调用的安全边界Agent 调用工具是有风险的尤其是涉及文件操作、网络请求、数据库写入的工具。cloudflare-os的做法是把每个工具调用放在独立的 Worker 请求里执行天然有隔离。但开发者仍然需要自己做权限校验。我的做法是在工具 handler 里加一层validate函数检查调用参数是否符合预期。比如一个删除文件的工具必须校验路径是否在允许的目录内。这个检查不能省因为模型可能会被诱导生成恶意参数。提示工具 handler 里不要直接信任模型生成的参数所有输入都要当作不可信数据处理。4.3 多 Agent 协作的实操配置多 Agent 协作是cloudflare-os的亮点。假设你有两个 Agent一个负责理解用户意图一个负责执行具体任务。它们之间的通信通过 DO 的 RPC 实现。export class RouterAgent extends Agent { async onRequest(request: Request) { const { message } await request.json(); const executorId this.env.EXECUTOR.idFromName(executor); const executor this.env.EXECUTOR.get(executorId); const result await executor.fetch(new Request(https://internal/execute, { method: POST, body: JSON.stringify({ task: message }) })); return new Response(await result.text()); } }这种模式下RouterAgent 和 ExecutorAgent 是独立部署、独立扩展的。RouterAgent 可以水平扩展多个实例ExecutorAgent 保持单实例以保证状态一致。我实测下来这种架构比把所有逻辑塞进一个 Agent 要清晰得多调试时也能单独测试每个 Agent。5. 状态管理与记忆持久化Agent 不应该是金鱼5.1 Durable Objects 的存储模型Durable Objects 提供了两种存储storage和state。storage是持久化的写入后即使 DO 被回收也不会丢失state是内存中的DO 重启后会丢失。Agents SDK 的setState默认写入storage但如果你需要高频读写可以用内存缓存减少 IO。// 持久化写入 await this.setState({ conversationHistory: history }); // 内存缓存 this.memoryCache history;我一般会把对话历史放在storage里把当前任务进度放在内存里。因为对话历史需要跨会话保留而任务进度在 DO 重启后重新计算即可。5.2 记忆的压缩与检索Agent 的记忆不能无限增长否则 DO 的存储会爆掉而且每次读取全量历史会拖慢响应。我的做法是定期对历史做摘要压缩当对话超过 50 轮时用 Workers AI 生成一个摘要替换掉原始历史。async compressHistory() { const history await this.getState(conversationHistory); if (history.length 50) return; const summary await this.env.AI.run( cf/meta/llama-3-8b-instruct, { messages: [{ role: user, content: 总结以下对话${JSON.stringify(history)} }] } ); await this.setState({ conversationHistory: [{ role: system, content: summary.response }] }); }这个压缩策略在长会话场景下效果很好能把存储占用降低 80% 以上同时保留关键信息。5.3 跨 Agent 的状态共享有时候多个 Agent 需要共享状态比如一个用户画像 Agent 和一个推荐 Agent。直接让它们互相调用会增加耦合更好的做法是用一个独立的SharedStateDurable Object 作为中介。export class SharedState extends Agent { async getUserProfile(userId: string) { return await this.getState(profile:${userId}); } async setUserProfile(userId: string, profile: any) { await this.setState({ [profile:${userId}]: profile }); } }这种设计下任何 Agent 都可以通过SharedState读写用户画像而不需要知道其他 Agent 的存在。我把它称为“状态总线”模式在复杂系统里非常实用。6. 常见问题与排查技巧实录6.1 Durable Objects 迁移失败这是新手最容易遇到的问题。症状是部署时报错Cannot find class MyAgent或Migration tag already exists。原因通常是wrangler.toml里的migrations配置和实际代码不一致。排查步骤检查new_classes里的类名是否和代码里的export class完全一致大小写敏感。每次新增 DO 类必须新增一个 migration tag不能复用旧的。如果本地调试正常但部署失败尝试删除node_modules/.cache后重新部署。6.2 Workers AI 调用超时Workers AI 的模型推理有时间限制默认 30 秒。如果模型输出很长可能会超时。解决办法是设置stream: true用流式响应逐步返回结果。const stream await this.env.AI.run( cf/meta/llama-3-8b-instruct, { messages, stream: true } ); return new Response(stream, { headers: { Content-Type: text/event-stream } });流式响应不仅避免超时还能显著提升用户体验因为用户不用等全部生成完才看到内容。6.3 Agent 间 RPC 调用失败多 Agent 协作时RPC 调用可能因为 DO 实例未初始化而失败。我的经验是加一个重试机制async callWithRetry(stub, request, retries 3) { for (let i 0; i retries; i) { try { return await stub.fetch(request); } catch (e) { if (i retries - 1) throw e; await new Promise(r setTimeout(r, 100 * (i 1))); } } }指数退避重试在分布式系统里是标配能解决大部分瞬时故障。6.4 常见问题速查表问题现象可能原因解决方法部署报错 Cannot find classmigrations 配置错误检查类名和 tag新增 migrationAI 调用超时输出过长启用 stream 模式RPC 调用失败DO 未初始化加重试机制检查 idFromName状态丢失用了内存存储改用 setState 持久化冷启动慢依赖过多精简 import用动态导入7. 安全与可观测性生产环境不能裸奔7.1 Agent 安全的三层防护Agent 安全是我最看重的部分。cloudflare-os提供了基础隔离但开发者还需要自己做三层防护。第一层是输入校验所有用户输入都要过滤防止 prompt 注入。第二层是工具权限每个工具都要有明确的权限声明敏感操作需要二次确认。第三层是输出审查Agent 生成的回复要经过敏感词过滤再返回给用户。function sanitizeInput(input: string): string { return input.replace(/[]/g, ).slice(0, 2000); }这个简单的过滤能挡住大部分基础攻击。更复杂的场景可以用 Workers AI 做意图识别判断输入是否包含恶意指令。7.2 日志与追踪wrangler tail是调试 Agent 的利器能实时看到所有请求和日志。但生产环境需要更持久的日志存储。我的做法是把关键事件写入一个独立的 Logging Durable Object定期导出到 R2 存储。await this.env.LOGGER.get(id).fetch(new Request(https://internal/log, { method: POST, body: JSON.stringify({ event: tool_call, tool: get_weather, timestamp: Date.now() }) }));这种集中式日志在排查多 Agent 协作问题时特别有用因为你能看到完整的调用链路。7.3 成本控制Workers AI 和 Durable Objects 都是按用量计费的不加控制很容易超预算。我的经验是设置每日配额超过后降级到更小的模型或直接返回缓存结果。另外DO 的存储要定期清理过期的对话历史及时删除。提示在 wrangler.toml 里可以设置[limits]来限制 DO 的存储和请求量防止意外流量导致账单爆炸。8. 我对 cloudflare-os 的实际体会跑完几个小项目之后我对cloudflare-os的感受是它把 Agent 开发从“手工作坊”推向了“工业化”。以前写 Agent 要自己搭状态层、自己做隔离、自己处理扩展现在这些都由平台兜底了。代价是绑定 Cloudflare 生态迁移成本不低。但如果你的用户分布在全球或者你的 Agent 需要低延迟响应这个代价是值得的。我踩过的最大的坑是低估了 Durable Objects 的冷启动。虽然 V8 Isolate 本身很快但 DO 实例首次加载时仍然有几百毫秒的延迟。解决办法是预热在部署后主动发几个请求把常用 DO 实例唤醒。这个技巧官方没提但实测能显著改善首屏体验。另外一个小技巧是把 Agent 的配置和 prompt 模板放在环境变量里而不是硬编码在代码中。这样调整 prompt 不需要重新部署改完环境变量立即生效。对于需要频繁调优的场景这个做法能省下大量时间。