Cloudflare Workers 边缘计算：构建 AI Agent 的架构与实践

1. 从标题到本质cloudflare-os 到底在解决什么问题第一次看到cloudflare-os这个项目名很多人会下意识以为 Cloudflare 又出了一个操作系统。其实不是。它更像是一套“把 Cloudflare 边缘网络当成一台分布式计算机来用”的工程实践集合核心载体是Cloudflare Workers而它真正想回答的问题是当 AI Agent 需要长期在线、需要记忆、需要工具调用、需要被调度时我们能不能不自己养服务器而是把整个运行时托管到边缘节点上。我最初关注这个方向是因为在做agent 开发时反复遇到同一个矛盾Agent 本身逻辑不复杂但它的“生存环境”很麻烦。你要给它一个能接收消息的入口要给它存agent 记忆的地方要让它能定时醒来干活还要在它调用外部工具时保证低延迟。传统做法是买一台小服务器跑一个常驻进程再配数据库和队列。这套东西能跑但维护成本高而且一旦 Agent 数量变多资源利用率非常难看。cloudflare-os这类项目的价值就在这里。它把 Agent 拆成“无状态的计算单元 有状态的存储 事件驱动的调度”然后全部塞进 Cloudflare 的边缘体系里。Workers 负责执行Durable Objects 负责状态和协调KV 负责冷数据R2 负责对象存储Queues 负责异步任务Cron Triggers 负责定时唤醒。你不需要关心某台机器在哪只需要关心 Agent 的行为逻辑。这套思路适合谁我认为有三类人特别值得看。第一类是独立开发者想做一个agent 项目但不想背服务器运维的包袱。第二类是做ai agent 搭建的团队需要快速验证多 Agent 协作的可行性。第三类是对agent 架构感兴趣、想理解“边缘计算 AI”怎么结合的技术人。哪怕你最后不用 Cloudflare这套拆解问题的方式也能迁移到别的平台。需要提前说明的是下面涉及的具体配置和代码结构一部分来自公开文档的常见实践一部分是我在实际搭建类似系统时的合理补全。我会尽量把“为什么这么选”讲清楚而不是只丢一堆配置让你抄。2. 整体架构设计为什么把 Agent 放到边缘上2.1 核心思路计算、状态、调度三分离传统 Agent 服务最容易犯的错是把所有东西揉进一个进程里。进程里既有对话逻辑又有记忆读写还有定时任务和工具调用。刚开始跑没问题一旦要扩容或者要支持多个 Agent 并行就会变成一团乱麻。cloudflare-os的思路是把这三件事彻底拆开。计算层用Cloudflare Workers。它天生无状态、按请求计费、全球分布。一个 Worker 被调用时它不关心上一次是谁调用的只关心这次请求要做什么。这对 Agent 来说其实很合适因为 Agent 的“思考”本身可以设计成一次函数调用输入上下文输出动作或回复。状态层用Durable Objects。这是整个架构里最关键的一环。Durable Objects 可以理解成“有唯一名字的、单线程执行的小房间”。每个 Agent 可以对应一个 Durable Object它的记忆、会话历史、当前任务队列都放在这个房间里。因为单线程所以不会出现两个请求同时改同一份记忆导致冲突的问题。这一点在做agent 记忆时特别重要。调度层用Cron Triggers Queues。Agent 不是每次都要等人来触发它可能需要定时检查任务、定时总结记忆、定时清理过期数据。Cron Triggers 负责按时间唤醒 WorkerQueues 负责把耗时的任务异步化避免阻塞主请求。提示不要把 Durable Objects 当成普通数据库用。它的优势是“单点协调”不是“海量存储”。大量冷数据应该放 KV 或 R2Durable Objects 只保留热状态。2.2 为什么不用传统服务器有人会问我用一台云主机跑 Node.js 不也能做 Agent 吗能但有几个现实问题。第一是冷启动和延迟。传统服务器如果为了省钱而休眠唤醒要几秒如果不休眠就一直烧钱。Workers 的冷启动通常在毫秒级而且只在有请求时计费。第二是分布。你的用户可能在各地传统服务器只有一个区域边缘节点天然离用户更近。第三是运维。没有操作系统要打补丁没有进程要守护没有磁盘要扩容。当然边缘方案也有代价。Workers 的运行时有约束比如不能随便开长连接、不能依赖本地文件系统、CPU 时间有限。所以cloudflare-os这类项目在设计时必须把“重活”拆成小块用事件驱动的方式串起来。这不是缺点而是一种强制你写好架构的约束。2.3 多 AI 协作在边缘上的落地方式多 ai 协作是热词里很显眼的一个。在边缘架构里多 Agent 协作可以有两种模式。一种是“编排式”一个主 Agent 负责拆任务然后把子任务分发给其他 Agent每个 Agent 是一个独立的 Durable Object。另一种是“黑板式”多个 Agent 共享一个协调对象通过读写同一个状态来协作。我实测下来编排式更适合任务边界清晰的场景比如一个 Agent 负责检索一个负责总结一个负责格式化输出。黑板式更适合需要频繁交换中间结果的场景但要注意锁竞争。Durable Objects 的单线程特性让黑板式不会出现数据竞争但会让协调对象成为瓶颈所以协作规模不宜太大。3. 核心细节解析Agent 运行时的关键部件3.1 Agent 的身份与路由设计每个 Agent 需要一个稳定身份。最直接的做法是用一个字符串 ID比如agent:weather或agent:user-123。这个 ID 用来定位对应的 Durable Object。路由层收到请求后根据 ID 找到对象把请求转发过去。这里有个容易踩的坑ID 的设计要避免热点。如果你把所有请求都路由到同一个 Agent ID那这个 Durable Object 就会成为单点。合理的做法是按用户或按会话分片比如agent:user-123:session-456。这样每个会话有独立状态互不干扰。// 路由层示意根据 agentId 获取 Durable Object stub const id env.AGENT_DO.idFromName(agentId); const stub env.AGENT_DO.get(id); return stub.fetch(request);这段代码看起来简单但idFromName的语义是“同名同对象”。也就是说只要 agentId 一样无论请求从哪个边缘节点进来最终都会落到同一个 Durable Object 上。这正是我们需要的“全局唯一 Agent 实例”。3.2 记忆系统的分层存储agent 记忆不能只放一个地方。我的做法是分三层。第一层是“工作记忆”放在 Durable Object 的内存或内置存储里保存当前会话的最近几轮对话读写最快。第二层是“短期记忆”放在 Durable Object 的持久化存储里保存最近几天或几十条记录用于跨请求恢复上下文。第三层是“长期记忆”放到 KV 或 R2保存总结后的知识、用户偏好、历史归档。为什么要分层因为成本和速度不一样。Durable Object 存储快但容量有限KV 便宜但延迟略高R2 适合大对象但不适合频繁小读写。把不同热度的数据放到不同层是边缘架构的基本功。注意写入长期记忆时要做压缩或摘要不要把原始对话一股脑塞进去。否则检索会变慢成本也会上升。3.3 工具调用与外部 API 的边界Agent 要干活就得调工具。在 Workers 里调外部 API 很直接用fetch就行。但有几个细节要注意。第一是超时控制外部 API 可能很慢必须设置合理的超时避免 Worker 被拖死。第二是错误处理外部 API 失败时要返回结构化错误让 Agent 能决定重试还是换方案。第三是密钥管理不要把 API Key 写死在代码里用环境变量或 Secrets。async function callTool(url, payload, timeoutMs 5000) { const controller new AbortController(); const timer setTimeout(() controller.abort(), timeoutMs); try { const res await fetch(url, { method: POST, body: JSON.stringify(payload), signal: controller.signal, }); if (!res.ok) throw new Error(tool failed: ${res.status}); return await res.json(); } finally { clearTimeout(timer); } }这段代码的关键是AbortController。没有它一个卡住的外部调用可能让整个 Agent 请求超时。加上它之后超时会被转换成异常Agent 可以捕获并决定下一步。3.4 调度与异步任务Agent 有些活不适合在请求里同步做比如批量总结、定时巡检、长文档处理。这些应该丢给 Queues。Worker 收到请求后把任务写进队列立刻返回“已受理”。另一个 Worker 消费队列慢慢处理。这样用户体验好也不会因为 CPU 时间超限而失败。Cron Triggers 则用来做周期性唤醒。比如每小时让 Agent 检查一次待办每天凌晨做一次记忆整理。配置方式是在wrangler.toml里声明 cron 表达式然后 Worker 里判断事件类型。[triggers] crons [0 * * * *, 0 3 * * *]第一个表达式表示每小时整点触发第二个表示每天凌晨三点触发。Worker 里可以通过event.cron区分是哪个任务。4. 实操过程从零搭一个最小可用 Agent4.1 环境准备与项目初始化先装 Wrangler这是 Cloudflare 的官方 CLI。然后创建一个新项目。我习惯用 TypeScript因为 Agent 逻辑里类型多有类型检查会少很多低级错误。npm install -g wrangler wrangler login npm create cloudflarelatest my-agent-os cd my-agent-os初始化时会问你用哪种模板。选 Worker TypeScript 就行。然后安装依赖配置wrangler.toml。这个文件是整个项目的骨架Durable Objects、KV、Queues、Cron 都在这里声明。name my-agent-os main src/index.ts compatibility_date 2024-01-01 [[durable_objects.bindings]] name AGENT_DO class_name AgentDurableObject [[kv_namespaces]] binding LONG_TERM_MEMORY id your-kv-id [[queues.producers]] binding TASK_QUEUE queue agent-tasks [triggers] crons [0 * * * *]提示compatibility_date不要随便改它决定了运行时行为。新项目用较新的日期老项目升级时要先看变更说明。4.2 Durable Object 的实现要点Durable Object 的类需要导出并在 Worker 里绑定。它的核心是处理fetch请求以及可选的alarm定时器。下面是一个简化版实现包含记忆读写和基本对话逻辑。export class AgentDurableObject { state: DurableObjectState; memory: string[] []; constructor(state: DurableObjectState) { this.state state; this.state.blockConcurrencyWhile(async () { const stored await this.state.storage.getstring[](memory); this.memory stored ?? []; }); } async fetch(request: Request): PromiseResponse { const url new URL(request.url); if (url.pathname /chat) { const body await request.json{ text: string }(); this.memory.push(body.text); if (this.memory.length 20) this.memory.shift(); await this.state.storage.put(memory, this.memory); return new Response(JSON.stringify({ reply: 收到${body.text} }), { headers: { content-type: application/json }, }); } return new Response(not found, { status: 404 }); } }这里有几个关键点。blockConcurrencyWhile保证在初始化完成前不会处理请求避免读到空记忆。记忆长度做了截断防止无限增长。每次写入都持久化保证重启后还能恢复。4.3 请求入口与路由Worker 的入口负责解析请求找到对应的 Durable Object然后转发。同时它也可以处理不需要状态的请求比如健康检查。export default { async fetch(request: Request, env: Env): PromiseResponse { const url new URL(request.url); const agentId url.searchParams.get(agent) ?? default; const id env.AGENT_DO.idFromName(agentId); const stub env.AGENT_DO.get(id); return stub.fetch(request); }, };这个入口非常薄所有逻辑都在 Durable Object 里。这样做的好处是路由层可以随便扩容而状态始终集中在对应的对象上。4.4 队列消费与定时任务队列消费者和定时任务可以放在同一个 Worker 里通过导出不同的处理函数来区分。export default { async fetch(request, env) { /* 上面的路由逻辑 */ }, async queue(batch, env) { for (const msg of batch.messages) { // 处理异步任务比如总结记忆 console.log(processing, msg.body); msg.ack(); } }, async scheduled(event, env, ctx) { // 定时任务比如每小时巡检 console.log(cron fired, event.cron); }, };queue处理批量消息scheduled处理定时事件。两者都不需要用户请求触发是 Agent 自主行为的基础。4.5 部署与验证部署用wrangler deploy。部署完成后可以用curl测试。curl https://my-agent-os.your-subdomain.workers.dev/chat?agenttest \ -X POST -H content-type: application/json \ -d {text:你好}如果返回了回复说明路由和 Durable Object 都通了。然后再测记忆是否持久发两条消息重启后再发一条看之前的记忆是否还在。这一步很多人会忽略但它是验证状态层是否正确的关键。5. 常见问题与排查技巧实录5.1 Durable Object 报错找不到类最常见的问题是wrangler.toml里声明了 Durable Object 绑定但代码里没有导出对应的类或者类名拼写不一致。排查方法是先看部署日志再看绑定配置和导出名是否完全一致。大小写敏感AgentDurableObject和agentDurableObject是两个东西。5.2 记忆丢失或串号如果发现不同 Agent 的记忆混在一起大概率是idFromName用的 ID 不对。检查路由层是否把用户 ID 或会话 ID 正确拼进了 agentId。另一个可能是 Durable Object 的存储键名冲突比如所有数据都写在memory这个键下不同逻辑互相覆盖。建议按用途分键比如memory:chat、memory:summary。5.3 请求超时或 CPU 超限Workers 有 CPU 时间限制。如果 Agent 逻辑里有大量循环或复杂计算很容易超限。解决办法是把重活拆到队列里异步做请求里只做轻量决策。另外外部 API 调用要设超时避免因为第三方慢而拖垮自己。5.4 队列消息重复消费Queues 保证至少一次投递所以消息可能重复。消费逻辑要幂等比如用消息 ID 去重或者让操作本身可重复执行而不产生副作用。这一点在做记忆写入时尤其重要重复写入会导致记忆膨胀。5.5 常见问题速查表问题现象可能原因排查方向部署失败提示绑定错误配置与代码不一致检查 wrangler.toml 和导出类名请求 500日志无详细信息未捕获异常加 try/catch输出结构化错误记忆不持久未调用 storage.put检查写入路径是否执行定时任务不触发cron 表达式错误用在线工具验证表达式队列积压消费者处理太慢增加批量大小或拆分任务提示排查边缘应用时日志是唯一可靠的线索。养成在关键路径打日志的习惯但不要打敏感数据。5.6 几个我踩过的坑第一个坑是以为 Durable Object 可以无限存。实际上它有容量限制而且存储操作有延迟。大量小写入会拖慢响应。后来我改成批量写入把多次记忆更新合并成一次。第二个坑是忽略冷启动。虽然 Workers 冷启动很快但 Durable Object 首次加载状态时仍需要时间。如果 Agent 对首响应延迟敏感可以在初始化时预热或者把常用状态缓存在内存里。第三个坑是密钥管理。早期我把 API Key 写在代码里后来改用 Secrets。部署时用wrangler secret put写入代码里通过env读取。这样既安全又方便轮换。6. 扩展方向这套架构还能怎么用cloudflare-os的思路不局限于聊天 Agent。它可以扩展成很多形态。比如做一个agent 画图的调度器把绘图任务丢给队列生成后存到 R2再通知用户。或者做一个ai 测试开发的辅助工具让 Agent 定时跑测试用例把结果写回 KV。再或者做多 ai 协作的研究平台用多个 Durable Object 模拟不同角色的 Agent观察它们如何通过消息传递完成任务。我个人觉得最有意思的方向是“Agent 的自我维护”。让 Agent 定时回顾自己的记忆做摘要、去重、归档。这需要 Cron 和队列配合但一旦跑起来Agent 就能在无人干预的情况下保持记忆整洁。这个能力在长期运行的 Agent 项目里非常关键。如果你打算动手我的建议是先跑通最小闭环一个 Worker一个 Durable Object一次对话一次持久化。然后再逐步加队列、加定时、加多 Agent。不要一上来就设计大而全的架构边缘开发的乐趣就在于小步快跑每一步都能立刻验证。