Cloudflare Agents SDK 构建指南
帮助开发者在 Cloudflare Workers 上构建具备持久状态、实时通信和可靠后台执行能力的 AI Agent。
材料包含 OAuth、HMAC、安全回复、密钥存储、MCP 加固及人工审批示例，显示出部分安全意识；但涉及邮件、浏览器、Webhook、推送、MCP 和代码执行等外部影响时，未系统说明最小权限、完整数据流、敏感数据处理、回滚或用户确认边界，因此扣分。
文档结构和示例相互基本一致，覆盖安装、配置、核心 API、恢复、重试和异常提示；但多个引用文件仅要求继续读取外部文档，缺少本地测试、版本锁定、关键路径复现证据及统一错误处理。按静态校准，不能超过10分，故扣分。
前置描述明确面向在 Cloudflare Workers 上构建有状态代理、工作流、实时应用、MCP、聊天、语音和浏览器自动化，触发场景较清楚；但非适用边界、输入输出契约和语义触发条件不够完整，且核心检索依赖 Cloudflare 海外文档，未说明中国大陆网络可达性或中文支持，因此扣分。
具备分层目录、安装命令、配置示例、参考文件、实验性标记、Apache-2.0 许可证和迁移注意事项；但缺少明确的 SDK/文档版本、变更日志、维护责任人、更新路径、常见故障排查和系统化限制说明，因此扣分。
内含可直接改编的 TypeScript、React、Wrangler 和 API 示例，并覆盖较多 Agents SDK 功能，核心指导价值明确；但示例未执行验证，部分内容依赖外部文档且复杂场景仍需用户自行整合、鉴权和测试。静态校准最高7分，故取上限。
提供了大量指向 Cloudflare 官方文档的主题映射和可审计代码片段，具备有限的主要来源追踪性；但没有提交测试套件、CI 覆盖关键路径或第三方复现结果，且本次仅静态阅读，因此不超过5分。
- 核心能力覆盖邮件、浏览器自动化、MCP、Webhook、推送和代码执行，部署前应逐项审查权限、鉴权、数据外传、人工审批和回滚方案。
- 引用的 Cloudflare 文档需要联网检索；应确认目标环境可访问，并在中国大陆网络受限时准备镜像、缓存或本地版本。
- 示例未在本次审查中执行，不能据此确认 API 版本兼容性、迁移正确性或生产稳定性。
- 未提供明确版本、变更日志和维护责任，升级 SDK 前应重新核对所有外部引用。
这个 Skill 能做什么，适合哪些场景？
该技能面向使用 Cloudflare Agents SDK 构建 AI Agent 的开发者。它涵盖 Agent 类、持久状态、WebSocket、可调用 RPC、定时任务、Workflows、队列、重试、MCP、聊天应用和 React 客户端钩子。技能要求优先检索 Cloudflare Agents 文档，以降低预训练知识过时带来的风险。语音、浏览器工具和 Think 被明确标为实验性功能。
指导用户检查并安装 agents npm 包，配置 Wrangler 中的 Durable Objects、SQLite 迁移和 Workers AI 绑定，编写 Agent 类、状态校验、RPC 方法和路由。它还提供调度、工作流、持久执行、队列、重试、聊天流、MCP、邮件、Webhook、推送通知、可观测性及 React 客户端的 API 示例，并指向对应的 Cloudflare 文档和本地参考文件。
- 开发者需要在 Cloudflare Workers 上创建带持久状态的聊天 Agent 或协作应用时使用。
- 团队需要通过 WebSocket、RPC 和 React hooks 构建实时客户端体验时使用。
- 工程师需要运行可恢复的多步骤后台任务、队列任务或带重试逻辑的工作流时使用。
- 开发者需要让 Agent 连接 MCP 服务或在 Cloudflare 上构建 MCP 服务器时使用。
- 团队需要为 Agent 增加定时任务、邮件处理、Webhook、推送通知或观测事件时使用。
这个 Skill 有哪些优点和局限？
- 覆盖从 Agent 类和状态管理到工作流、队列、重试、聊天流和 MCP 的完整开发路径。
- 提供 Wrangler 配置、路由、RPC、React hooks 等可直接参考的代码示例。
- 明确提醒优先检索官方文档，适合 Agents SDK 可能快速变化的场景。
- 主要适用于 Cloudflare Workers 与 Agents SDK 生态，不是通用 Agent 开发指南。
- 语音、浏览器工具和 Think 功能仍标记为实验性。
- 来源未提供独立测试套件、性能数据或成本评估。
如何安装这个 Skill？
该技能属于 cloudflare/skills 集合。可运行 npx skills add https://github.com/cloudflare/skills 安装集合；也可将对应技能目录复制到所用 Agent 客户端的技能目录，例如 OpenAI Codex 使用 ~/.codex/skills/。仓库未说明单独安装 agents-sdk 技能的专用命令。
如何使用这个 Skill？
在支持 Agent Skills 标准的客户端中提出与 Cloudflare Agents SDK 相关的请求，例如“在 Cloudflare Workers 上构建一个带持久状态和 WebSocket 的 AI Agent”。开始实现前，按技能建议访问 https://developers.cloudflare.com/agents/ 获取最新文档；项目中可先运行 npm ls agents，若未安装则运行 npm install agents。