大多数教你”在边缘部署 AI Agent”的文章，读完之后的感受是差不多的：概念都对，但代码得你自己写。Durable Objects 怎么配、WebSocket 路由怎么接、状态同步怎么处理，全是你的活。
Cloudflare 这个 building-ai-agent-on-cloudflare Skill 做的事情，就是把上面这些胶水代码替你写完。
它不是一个 AI Agent 框架，也不做什么创新性的架构设计。它只是把你本来要花半天手写的样板代码，压缩成了一条命令。这种定位听起来不够性感，但用起来是真的省事。
从文档结构和代码模板来看，它的设计逻辑很清晰：Agent 的核心价值在业务逻辑，不在基础设施。Durable Objects 的配置、Worker 的路由、AI binding 的声明，这些东西没有一项是你想手动写的。而且一旦你写错过一次 WebSocket 路由配置，你就会知道这类胶水代码有多容易出错，又有多难调试。这个 Skill 替你把脏活干了，你只需要填 agent 的行为。
环境准备
跑这个 Skill 的前置条件不多，但少一个都跑不动。
你需要一个 Cloudflare 账号，并且开通了 Workers 功能。Node.js 18 以上，Wrangler CLI 装好。这些是 Cloudflare Workers 开发的标配，如果你之前写过 Cloudflare Worker，环境应该已经是现成的。
安装这个 Skill 本身只有一行命令：
npx skills add https://github.com/cloudflare/skills --skill building-ai-agent-on-cloudflare
装完之后，在你的 AI 编码助手（Claude Code、CodeBuddy 等）里直接提需求就行。这一步没什么坑，但有一点值得注意：这个 Skill 生成的代码依赖 agents 这个 npm 包，而这个包的 API 还在快速迭代中。如果你看到的示例代码跟最新文档对不上，先查 Cloudflare Agents SDK 的 changelog，别在自己代码里死磕。
验证安装是否成功倒也简单。随便让你的 AI 助手生成一个 agent starter 项目，跑 npm start，在 http://localhost:8787 能看到响应就行。
操作流程
这个 Skill 的工作方式跟大部分代码生成类 Skill 一样：你描述需求，它生成代码。但它的生成质量，取决于你对 Cloudflare Agents SDK 的理解程度。
第一步，告诉它你想构建什么类型的 Agent。比如”帮我做一个客服对话 Agent，要记住用户的历史消息，支持断线重连”。它会直接生成一个完整的项目结构，包括 src/agent.ts（Agent 类定义）、src/index.ts（入口路由）、wrangler.jsonc（部署配置）。
第二步，它会自动处理那些你以为需要手动写的部分。Durable Object 的 binding 声明、routeAgentRequest 的路由配置、this.setState 和 this.state 的状态持久化，全都写好了。你看到的代码大概长这样：
export class ChatAgent extends Agent<Env, State> {
initialState: State = { messages: [] };
async onMessage(connection: Connection, message: string) {
const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
messages: [...this.state.messages, { role: "user", content: message }],
});
this.setState({
...this.state,
messages: [...this.state.messages, { role: "assistant", content: response.response }],
});
connection.send(JSON.stringify({ type: "response", content: response.response }));
}
}
第三步是部署。跑 npx wrangler deploy，Agent 就会跑在 Cloudflare 的全球边缘网络上。每个用户会话会被路由到一个独立的 Durable Object 实例，状态隔离、自动扩容，你不需要管。
整个流程最让我意外的是第三步的平滑程度。传统方案里，从本地跑通到生产部署之间有一堆配置要改：
-
域名绑定 -
环境变量（environment variables） -
Secrets 管理
但这个 Skill 生成的 wrangler.jsonc 已经把这些坑都填了。复杂场景下你还是得手动调，比如自定义域名绑定和多 environment 切换，这些不在模板覆盖范围内。
关键设计
这个 Skill 最聪明的地方，不是它生成了什么代码，而是它选择不生成什么。
它没有试图封装一套自己的 Agent 抽象层。你拿到的代码直接 import agents 包，直接 extend Agent 类，直接调用 this.setState 和 this.env.AI.run。这意味着生成出来的代码跟 Cloudflare 官方文档是完全对齐的，不需要学一套”Skill 专属 DSL”。
这一点跟很多代码生成 Skill 的做法完全不同。大部分 Skill 会为了”降低使用门槛”而引入一层中间抽象，结果是你永远搞不清楚底层到底在干什么。这个 Skill 反其道而行：它就是把你本来要照着文档手写的代码，帮你写了。
另一个值得讲的设计选择是状态管理的处理方式。每个 Agent 实例自带一个 SQLite 数据库，状态通过 this.setState 自动持久化和同步。这个设计意味着你可以在 agent 代码里随意读写状态，不用担心并发冲突或者数据丢失。Durable Objects 的强一致性语义替你兜了底。
但它也有明显的局限。生成的代码默认使用 Cloudflare Workers AI（@cf/meta/llama-3-8b-instruct），如果你想接入 OpenAI 或其他模型，需要自己改 src/agent.ts 里的模型调用逻辑。Skill 不会帮你做模型切换，它假设你用的是 Cloudflare 生态内的模型。从架构推断，这是有意为之：Workers AI 跟 Durable Objects 部署在同一边缘节点上，延迟最低，这个默认值是经过权衡的。
使用场景
从 Skill 生成的代码模板倒推，它的目标场景其实很集中。
最典型的场景是构建带状态的对话 Agent。比如客服机器人、个人助理、代码审查 bot。这类 Agent 的核心需求是记住上下文，用户在对话中提到的信息不能被下一次请求丢掉。传统做法是外接一个 Redis 或者数据库存会话状态，但 Durable Objects 直接把状态绑在 Agent 实例上，省掉了一层外部依赖。
第二个场景是定时任务驱动的 Agent。Agent 不只是被动响应，它可以主动做事。比如每天早上 9 点生成一份项目进度摘要，或者每隔一小时检查一次监控告警状态。Skill 生成的代码模板里预留了 this.schedule 的调用位置，你只需要填上 cron 表达式和任务逻辑。
第三个场景更有意思：多人实时协作。同一个 Agent 实例可以被多个客户端通过 WebSocket 同时连接，任何一端触发的状态变更会自动广播给其他端。这在协同编辑、共享白板、多人在线决策助手等场景里是天然优势。
不过有一个现实问题需要说明。这些场景目前都偏向原型验证阶段。30 次安装量（截至撰写时）意味着它还不是一个被广泛验证过的工具。文档中提到的 @cloudflare/codemode 和 AgentWorkflow 这些更高级的特性，在 Skill 生成的模板代码里也只是占位，实际使用时需要自己补充大量业务逻辑。
洞察与反思
说实话，这个 Skill 让我重新想了一个问题：AI 编码 Skill 的边界到底在哪。
它不做任何”智能”的事情。不帮你设计 Agent 架构，不帮你优化 Prompt，不帮你选择模型。它做的全部事情就是把 Cloudflare Agents SDK 的标准用法翻译成可运行的 TypeScript 代码。从这个角度看，它更接近一个”增强版脚手架”而不是”AI 编码助手”。
但恰恰是这种克制，让它比那些试图什么都帮你做的 Skill 更可靠。因为它的输出是确定的，你知道生成的代码跟官方文档会对齐，你知道出问题时能在官方文档里找到答案。这种可靠性，在需要”真正部署到生产”的场景里，比”看起来很智能但输出不可控”有价值得多。
Cloudflare 做这个 Skill 的动机也不难推断。Agents SDK 本身是新的，文档在快速迭代，用传统方式写教程跟不上 SDK 的更新速度。一个能根据最新 SDK 版本自动调整输出代码的 Skill，比任何静态文档都更能降低开发者的上手成本。这是”文档即代码”思路的一个务实落地。
让我比较在意的一点是它对 Cloudflare 生态的强绑定。Workers AI 作为默认模型、Durable Objects 作为唯一的状态方案、Wrangler 作为唯一的部署工具，这个 Skill 几乎是 Cloudflare 全家桶的强制入口。短期来看降低了复杂度，长期来看迁移成本不低。如果你的 Agent 以后需要跑在 AWS 或 Vercel 上，这里的代码基本都需要重写。
资源地址
| 资源 | 地址 |
|---|---|
| Smithery 页面 | https://smithery.ai/skills/cloudflare/building-ai-agent-on-cloudflare |
| GitHub 仓库 | https://github.com/cloudflare/skills/tree/main/skills/building-ai-agent-on-cloudflare |
| Cloudflare Agents SDK 文档 | https://developers.cloudflare.com/agents/ |
总结
这个 Skill 解决了 Cloudflare Agents SDK 上手过程中最无聊的那部分工作：
-
写样板代码 -
配 Durable Objects binding -
接 WebSocket 路由 -
声明 AI binding
它做得很克制，没有引入额外的抽象层，输出跟官方文档对齐。
但它不会帮你做架构决策。Agent 的逻辑粒度怎么划分、多 Agent 之间怎么通信、模型选型怎么权衡，这些问题仍然需要你自己想清楚。Skill 只是替你省掉了从”我想做”到”我能跑”之间的那一步。
如果你已经在用 Cloudflare Workers 做后端，想试试 Agent 化的方向，这个 Skill 值得花十分钟跑一遍。如果你还没决定用哪个平台部署 Agent，建议先把 Cloudflare Agents SDK 的官方文档翻一遍，再决定这个生态适不适合你。