尧图网站建设 
Cloudflare Agents SDK 常见问题排查与生产实践Gotchas、配额限制与最佳实践【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文围绕 Cloudflare Agents SDK构建在 Durable Objects 之上的 AI Agent 框架的故障排查文档展开系统梳理了开发与上线过程中最高频的 10 类踩坑点、平台配额/限流上限以及状态管理、SQL、调度、WebSocket、AI 集成与生产部署的实践准则。读完本文你将掌握setState同步、消息历史裁剪、参数化 SQL、WebSocket 握手、可恢复流、MCP 休眠重注册等关键问题的标准解法并能在编码阶段规避配额风险直接用于 agents-sdk/gotchas.md 所对应的真实 Agent 项目。文档定位什么时候该看 Gotchas在 Agents SDK 的参考文档体系中README.md 给出了明确的阅读顺序快速上手只看 README构建聊天 Agent 走 README → api.md → patterns.md而排错Debug issues阶段则直接看 gotchas.md。也就是说本文内容对应的场景是你的 Agent 已经能跑起来但在状态同步、消息持久化、WebSocket、调度、AI 调用或配额上开始出现诡异问题。下面按常见错误 → 配额速查 → 最佳实践三个层次逐一拆解。一、常见错误与标准解法1.1 setState() not syncing——状态为什么不同步根因直接修改状态对象mutation后没有调用setState()或调用时没有使用不可变更新immutable update。解法始终通过setState()配合展开语法做不可变更新// ❌ this.state.count // 直接改状态不触发同步 // ✅ this.setState({...this.state, count: this.state.count 1})这与 api.md 中State, SQL, Scheduling一节的 API 用法完全一致this.setState({count: 42})是自动同步的而递增计数器等场景必须基于当前this.state展开后再写入。在 patterns.md 的实时协作示例GameAgent中玩家分数更新也遵循同一模式this.setState({...this.state, players: ...})。可以把setState理解为用新对象替换旧对象任何绕过它的原地修改都会被框架忽略。1.2 Message history grows unbounded——AIChatAgent 消息历史无限增长根因AIChatAgent中的this.messages会无限累积所有历史消息最终导致 token 超限、内存与存储膨胀。解法在onChatMessage中定期手工裁剪只保留最近 N 条下例为 50 条export class ChatAgent extends AIChatAgentEnv { async onChatMessage(onFinish) { // Keep only last 50 messages if (this.messages.length 50) { this.messages this.messages.slice(-50); } return this.streamText({ model: openai(gpt-4), messages: this.messages, onFinish }); } }结合 README.md 可知AIChatAgent的核心卖点正是自动流式输出、消息历史、工具调用、可恢复流——自动管理消息历史是它的特性但也意味着你要为它的无限增长负责。更保险的生产做法是同时设置硬性上限例如 100 条见本文 3.6 节并配合 patterns.md 中通过onFinish持久化响应的用法把长对话归档到 SQL 而不是一直留在内存消息数组中。1.3 SQL injection vulnerability——SQL 注入漏洞根因在 SQL 语句中直接做字符串插值例如this.sql...WHERE id ${userId}把外部输入拼接进 SQL。解法始终使用参数化查询模板字符串占位符让框架负责转义// ❌ this.sql...WHERE id ${userId} // ✅ this.sql...WHERE id ${userId}api.md 明确强调SQL (parameterized queries prevent injection)其查询、插入示例均为参数化形式this.sqlINSERT INTO users (id,name) VALUES (${userId},${name})、this.sql{id,name}SELECT * FROM users WHERE id ${userId}。参数化模板在编译期把占位符与数据分离从根本上杜绝注入这一条同样适用于 patterns.md 中searchDocs工具对LIKE % query %的拼接写法——query 本身也应作为参数传入。1.4 WebSocket connection timeout——连接握手超时根因在onConnect中没有调用conn.accept()连接始终处于未接受状态直至超时。解法进入onConnect后立刻接受连接并设置连接级状态async onConnect(conn: Connection, ctx: ConnectionContext) { conn.accept(); conn.setState({userId: 123}); }对照 api.md 的生命周期钩子签名onConnect(conn: ConnectionConnState, ctx: ConnectionContext)conn.accept()是握手成功的前提之后才能conn.send(...)、conn.setState(...)、conn.close(code, reason)。底层 Durable Objects 的 WebSocket 语义durable-objects/gotchas.md同样要求显式 accept未接受的连接不会进入消息循环。1.5 Schedule limit exceeded——调度任务数超限根因每个 Agent 的调度任务超过 1000 个平台硬性上限继续schedule()会被拒绝。解法定期监控调度数量并清理已完成任务把创建速率控制在阈值内async checkSchedules() { if ((await this.getSchedules()).length 800) console.warn(Near limit!); }在 800 时就告警给后续清理留出余量。api.md 展示了三种调度方式schedule(new Date(...), ...)定时执行、schedule(60, ...)秒级延迟、schedule(0 0 * * *, ...)cron 周期执行并通过cancelSchedule(scheduleId)取消。生产上应在任务完成回调中主动取消避免只增不减。1.6 AI Gateway unavailable——AI 服务不可用根因AI 服务如 Workers AI超时或配额耗尽未处理异常导致整个请求失败。解法用 try/catch 包裹 AI 调用并提供降级fallback响应try { return await this.env.AI.run(model, {prompt}); } catch (e) { console.error(AI error:, e); return {error: Unavailable}; }api.md 中 Workers AI 的标准用法是this.env.AI.run(cf/meta/llama-3.1-8b-instruct, {prompt})configuration.md 还提供了通过 AI Gateway 转发以获得缓存与路由能力的可选配置在AI.run第三个参数中传入gateway: { id, skipCache, cacheTtl }。启用 Gateway 后超时与配额问题可通过缓存命中来缓解但 try/catch 兜底仍不可或缺。1.7 callable method returns undefined——RPC 方法返回 undefined根因callable()方法返回了无法 JSON 序列化的值如Date实例、类实例导致客户端拿不到预期结果。解法保证返回值是纯对象 / 数组 / 原始类型// ❌ Returns class instance callable() async getData() { return new Date(); } // ✅ Returns serializable object callable() async getData() { return { timestamp: Date.now() }; }这与 api.md 中callable的契约一致——Must return JSON-serializable values。RPC 方法经由 Durable Objects 的 RPC 通道传输任何非序列化类型都会在边界处丢失。客户端调用形态为const result await agent.processTask({ text: Hello })配合 React 侧的useAgent()即可在 WebSocket 上直接调用api.md Client Hooks 一节。1.8 Resumable stream not resuming——可恢复流无法恢复根因可恢复resumable流依赖确定性deterministic的 Stream ID若流 ID 不稳定或每次生成随机 ID断线后无法定位到原流。解法使用AIChatAgent即可自动获得可恢复能力无需手工管理流 ID// AIChatAgent handles this automatically export class ChatAgent extends AIChatAgentEnv { // Resumption works out of the box }从 README.md 的类选择表看Resumable可恢复正是AIChatAgent的关键特性之一api.md 也把auto-streaming, message history, tools, resumable streaming列为它的默认能力。若确实需要手工流式输出如 api.md 的手动流示例必须自行保证流 ID 的确定性生成策略。1.9 MCP connection loss on hibernation——休眠导致 MCP 连接丢失根因Agent 的 Durable Object 实例在空闲休眠后内存中的 MCP 服务器连接被清空恢复后找不到已注册的服务器。解法在onStart()中重新注册 MCP 服务器或先检查连接状态onStart() { // Re-register MCP servers after hibernation await this.mcp.registerServer(github, { url: env.MCP_URL, auth: {...} }); }onStart()是 Agent 的初始化/重启钩子api.md 生命周期一节冷启动与休眠唤醒都会经过它因此是幂等重注册的正确位置。MCP 的常规用法api.md MCP Integration 一节是registerServer()后通过getAITools([github])取得工具集再注入streamText。底层可参考 durable-objects/gotchas.md 的休眠即清内存语义所有非持久化的连接状态在休眠后都不再可靠必须可重建。1.10 Agent not found——Agent 找不到根因wrangler.jsonc中缺少对应的 Durable Object 绑定或绑定里的class_name与代码中导出的类名不一致。解法核对 configuration.md 的 wrangler 配置{ name: my-agents-app, durable_objects: { bindings: [ {name: MyAgent, class_name: MyAgent} ] }, migrations: [ {tag: v1, new_sqlite_classes: [MyAgent]} ], ai: { binding: AI } }三个要点绑定name决定env.MyAgent的访问名class_name必须与export class MyAgent extends AgentEnv完全一致且新类必须出现在migrations的new_sqlite_classes中首次迁移。多 Agent 场景下每个类都要有独立绑定与迁移条目。配好后路由层使用routeAgent(request, env)或按路径分发routeAgent(request, env, ChatAgent)即可自动命中对应 Agentconfiguration.md Agent Routing 一节。二、速率限制与配额速查表下表完整摘录自 gotchas.md是上线容量规划与排障的第一手依据其上限语义与 durable-objects/gotchas.md 的 Limits 表一致资源 / 限制数值说明单请求 CPU 时长30s默认300s最大在 wrangler.jsonc 中通过limits.cpu_ms配置单实例内存128MB与 WebSocket 缓冲共享单 Agent 存储10GBSQLite 存储调度任务数每 Agent 1000 个用getSchedules()监控WebSocket 连接数无限制受内存上限约束SQL 列数每表 100 列建表时需规划SQL 行大小2MBKey valueWebSocket 单条消息32MiB超限会被拒绝DO 请求吞吐约 1000 req/s按单个唯一 DO 实例计需要时做分片AI GatewayWorkers AI依模型而定以 Dashboard 展示的配额为准MCP 请求取决于服务端建议实现重试 / 退避结合源码文档可补充两点实操提示CPU 上限对应 durable-objects/gotchas.md 中的CPU time max 300s vialimits.cpu_ms超过默认 30s 的请求应主动调大或分块处理而 ~1000 req/s 是单实例软限吞吐要求更高时应参照该文档的Sharding分片思路将负载分散到多个 DO 实例。三、最佳实践清单3.1 状态管理State Management始终用不可变更新setState({...this.state, key: newValue})周期性裁剪无界数组消息、日志避免存储与内存膨胀大数据放 SQL不要塞进状态——状态保存在内存与存储中远超 SQL 合适负载的数据会拖垮实例128MB 内存上限。3.2 SQL 使用SQL Usage建表放在onStart()不要在onRequest()里建——onStart()每次实例初始化/唤醒都会执行保证表结构就绪且幂等api.md 中onStart()即用于CREATE TABLE IF NOT EXISTS使用参数化查询sqlWHERE id ${id}而不是sqlWHERE id ${id}为高频查询列建索引配合 100 列/2MB 行限制做好 schema 设计。3.3 调度Scheduling用await this.getSchedules()监控调度数量完成任务后主动cancelSchedule(scheduleId)取消保持在 1000 上限以内周期任务用 cron 字符串如0 0 * * *一次性任务用 Date 或秒级延迟api.md 调度示例。3.4 WebSocket始终在onConnect()中调用conn.accept()优雅处理客户端断开监听断开事件清理conn相关状态广播时高效遍历this.connections避免在循环内做重操作patterns.md 的聊天与游戏广播均为this.connections.forEach(c c.send(...))模式。3.5 AI 集成AI Integration聊天界面优先用AIChatAgent——自动流式输出、消息历史管理与断线恢复开箱即用裁剪消息历史以规避 token 与配额限制对应 1.2 节用 try/catch 降级响应处理 AI 错误对应 1.6 节需要缓存/路由时叠加 AI Gateway 配置configuration.md AI Gateway 一节。3.6 生产部署Production Deployment限流高流量 Agent1000 req/s实现请求节流避免打满单实例吞吐监控记录关键错误日志跟踪调度数量与存储用量getSchedules()、存储配额 10GB优雅降级AI 服务中断时给出可用的 fallback对应 1.6 节消息裁剪在AIChatAgent中强制执行最大历史长度如 100 条MCP 可靠性休眠后重新注册服务器对应 1.9 节并对 MCP 请求实现重试逻辑。四、故障排查决策要点速记把以上内容浓缩为上线前 checklist所有setState都是不可变更新状态里不放超大对象消息历史有硬性上限SQL 全部参数化表在onStart()建WebSocket 一律accept()MCP 服务器在onStart()幂等重注册调度任务做完成即取消超过 800 条告警callable返回值保证 JSON 可序列化AI 调用包 try/catch 并给 fallback必要时走 AI Gatewaywrangler.jsonc 的 DO 绑定class_name与代码类名、migrations 三者对齐对照第二节配额表做容量估算CPU 30s/300s、内存 128MB、存储 10GB、调度 1000、WebSocket 消息 32MiB。延伸阅读完整 API 与生命周期钩子见 agents-sdk/api.md项目初始化与 wrangler 路由、邮箱路由、AI Gateway、MCP 配置见 agents-sdk/configuration.md聊天工具、任务队列、邮件 AI 处理、实时协作等完整示例见 agents-sdk/patterns.md关于 Durable Objects 底层的休眠、迁移、并发与限额细节可参考 durable-objects/gotchas.md。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Agents SDK 常见问题排查与生产实践：Gotchas、配额限制与最佳实践
Cloudflare Agents SDK 常见问题排查与生产实践Gotchas、配额限制与最佳实践【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文围绕 Cloudflare Agents SDK构建在 Durable Objects 之上的 AI Agent 框架的故障排查文档展开系统梳理了开发与上线过程中最高频的 10 类踩坑点、平台配额/限流上限以及状态管理、SQL、调度、WebSocket、AI 集成与生产部署的实践准则。读完本文你将掌握setState同步、消息历史裁剪、参数化 SQL、WebSocket 握手、可恢复流、MCP 休眠重注册等关键问题的标准解法并能在编码阶段规避配额风险直接用于 agents-sdk/gotchas.md 所对应的真实 Agent 项目。文档定位什么时候该看 Gotchas在 Agents SDK 的参考文档体系中README.md 给出了明确的阅读顺序快速上手只看 README构建聊天 Agent 走 README → api.md → patterns.md而排错Debug issues阶段则直接看 gotchas.md。也就是说本文内容对应的场景是你的 Agent 已经能跑起来但在状态同步、消息持久化、WebSocket、调度、AI 调用或配额上开始出现诡异问题。下面按常见错误 → 配额速查 → 最佳实践三个层次逐一拆解。一、常见错误与标准解法1.1 setState() not syncing——状态为什么不同步根因直接修改状态对象mutation后没有调用setState()或调用时没有使用不可变更新immutable update。解法始终通过setState()配合展开语法做不可变更新// ❌ this.state.count // 直接改状态不触发同步 // ✅ this.setState({...this.state, count: this.state.count 1})这与 api.md 中State, SQL, Scheduling一节的 API 用法完全一致this.setState({count: 42})是自动同步的而递增计数器等场景必须基于当前this.state展开后再写入。在 patterns.md 的实时协作示例GameAgent中玩家分数更新也遵循同一模式this.setState({...this.state, players: ...})。可以把setState理解为用新对象替换旧对象任何绕过它的原地修改都会被框架忽略。1.2 Message history grows unbounded——AIChatAgent 消息历史无限增长根因AIChatAgent中的this.messages会无限累积所有历史消息最终导致 token 超限、内存与存储膨胀。解法在onChatMessage中定期手工裁剪只保留最近 N 条下例为 50 条export class ChatAgent extends AIChatAgentEnv { async onChatMessage(onFinish) { // Keep only last 50 messages if (this.messages.length 50) { this.messages this.messages.slice(-50); } return this.streamText({ model: openai(gpt-4), messages: this.messages, onFinish }); } }结合 README.md 可知AIChatAgent的核心卖点正是自动流式输出、消息历史、工具调用、可恢复流——自动管理消息历史是它的特性但也意味着你要为它的无限增长负责。更保险的生产做法是同时设置硬性上限例如 100 条见本文 3.6 节并配合 patterns.md 中通过onFinish持久化响应的用法把长对话归档到 SQL 而不是一直留在内存消息数组中。1.3 SQL injection vulnerability——SQL 注入漏洞根因在 SQL 语句中直接做字符串插值例如this.sql...WHERE id ${userId}把外部输入拼接进 SQL。解法始终使用参数化查询模板字符串占位符让框架负责转义// ❌ this.sql...WHERE id ${userId} // ✅ this.sql...WHERE id ${userId}api.md 明确强调SQL (parameterized queries prevent injection)其查询、插入示例均为参数化形式this.sqlINSERT INTO users (id,name) VALUES (${userId},${name})、this.sql{id,name}SELECT * FROM users WHERE id ${userId}。参数化模板在编译期把占位符与数据分离从根本上杜绝注入这一条同样适用于 patterns.md 中searchDocs工具对LIKE % query %的拼接写法——query 本身也应作为参数传入。1.4 WebSocket connection timeout——连接握手超时根因在onConnect中没有调用conn.accept()连接始终处于未接受状态直至超时。解法进入onConnect后立刻接受连接并设置连接级状态async onConnect(conn: Connection, ctx: ConnectionContext) { conn.accept(); conn.setState({userId: 123}); }对照 api.md 的生命周期钩子签名onConnect(conn: ConnectionConnState, ctx: ConnectionContext)conn.accept()是握手成功的前提之后才能conn.send(...)、conn.setState(...)、conn.close(code, reason)。底层 Durable Objects 的 WebSocket 语义durable-objects/gotchas.md同样要求显式 accept未接受的连接不会进入消息循环。1.5 Schedule limit exceeded——调度任务数超限根因每个 Agent 的调度任务超过 1000 个平台硬性上限继续schedule()会被拒绝。解法定期监控调度数量并清理已完成任务把创建速率控制在阈值内async checkSchedules() { if ((await this.getSchedules()).length 800) console.warn(Near limit!); }在 800 时就告警给后续清理留出余量。api.md 展示了三种调度方式schedule(new Date(...), ...)定时执行、schedule(60, ...)秒级延迟、schedule(0 0 * * *, ...)cron 周期执行并通过cancelSchedule(scheduleId)取消。生产上应在任务完成回调中主动取消避免只增不减。1.6 AI Gateway unavailable——AI 服务不可用根因AI 服务如 Workers AI超时或配额耗尽未处理异常导致整个请求失败。解法用 try/catch 包裹 AI 调用并提供降级fallback响应try { return await this.env.AI.run(model, {prompt}); } catch (e) { console.error(AI error:, e); return {error: Unavailable}; }api.md 中 Workers AI 的标准用法是this.env.AI.run(cf/meta/llama-3.1-8b-instruct, {prompt})configuration.md 还提供了通过 AI Gateway 转发以获得缓存与路由能力的可选配置在AI.run第三个参数中传入gateway: { id, skipCache, cacheTtl }。启用 Gateway 后超时与配额问题可通过缓存命中来缓解但 try/catch 兜底仍不可或缺。1.7 callable method returns undefined——RPC 方法返回 undefined根因callable()方法返回了无法 JSON 序列化的值如Date实例、类实例导致客户端拿不到预期结果。解法保证返回值是纯对象 / 数组 / 原始类型// ❌ Returns class instance callable() async getData() { return new Date(); } // ✅ Returns serializable object callable() async getData() { return { timestamp: Date.now() }; }这与 api.md 中callable的契约一致——Must return JSON-serializable values。RPC 方法经由 Durable Objects 的 RPC 通道传输任何非序列化类型都会在边界处丢失。客户端调用形态为const result await agent.processTask({ text: Hello })配合 React 侧的useAgent()即可在 WebSocket 上直接调用api.md Client Hooks 一节。1.8 Resumable stream not resuming——可恢复流无法恢复根因可恢复resumable流依赖确定性deterministic的 Stream ID若流 ID 不稳定或每次生成随机 ID断线后无法定位到原流。解法使用AIChatAgent即可自动获得可恢复能力无需手工管理流 ID// AIChatAgent handles this automatically export class ChatAgent extends AIChatAgentEnv { // Resumption works out of the box }从 README.md 的类选择表看Resumable可恢复正是AIChatAgent的关键特性之一api.md 也把auto-streaming, message history, tools, resumable streaming列为它的默认能力。若确实需要手工流式输出如 api.md 的手动流示例必须自行保证流 ID 的确定性生成策略。1.9 MCP connection loss on hibernation——休眠导致 MCP 连接丢失根因Agent 的 Durable Object 实例在空闲休眠后内存中的 MCP 服务器连接被清空恢复后找不到已注册的服务器。解法在onStart()中重新注册 MCP 服务器或先检查连接状态onStart() { // Re-register MCP servers after hibernation await this.mcp.registerServer(github, { url: env.MCP_URL, auth: {...} }); }onStart()是 Agent 的初始化/重启钩子api.md 生命周期一节冷启动与休眠唤醒都会经过它因此是幂等重注册的正确位置。MCP 的常规用法api.md MCP Integration 一节是registerServer()后通过getAITools([github])取得工具集再注入streamText。底层可参考 durable-objects/gotchas.md 的休眠即清内存语义所有非持久化的连接状态在休眠后都不再可靠必须可重建。1.10 Agent not found——Agent 找不到根因wrangler.jsonc中缺少对应的 Durable Object 绑定或绑定里的class_name与代码中导出的类名不一致。解法核对 configuration.md 的 wrangler 配置{ name: my-agents-app, durable_objects: { bindings: [ {name: MyAgent, class_name: MyAgent} ] }, migrations: [ {tag: v1, new_sqlite_classes: [MyAgent]} ], ai: { binding: AI } }三个要点绑定name决定env.MyAgent的访问名class_name必须与export class MyAgent extends AgentEnv完全一致且新类必须出现在migrations的new_sqlite_classes中首次迁移。多 Agent 场景下每个类都要有独立绑定与迁移条目。配好后路由层使用routeAgent(request, env)或按路径分发routeAgent(request, env, ChatAgent)即可自动命中对应 Agentconfiguration.md Agent Routing 一节。二、速率限制与配额速查表下表完整摘录自 gotchas.md是上线容量规划与排障的第一手依据其上限语义与 durable-objects/gotchas.md 的 Limits 表一致资源 / 限制数值说明单请求 CPU 时长30s默认300s最大在 wrangler.jsonc 中通过limits.cpu_ms配置单实例内存128MB与 WebSocket 缓冲共享单 Agent 存储10GBSQLite 存储调度任务数每 Agent 1000 个用getSchedules()监控WebSocket 连接数无限制受内存上限约束SQL 列数每表 100 列建表时需规划SQL 行大小2MBKey valueWebSocket 单条消息32MiB超限会被拒绝DO 请求吞吐约 1000 req/s按单个唯一 DO 实例计需要时做分片AI GatewayWorkers AI依模型而定以 Dashboard 展示的配额为准MCP 请求取决于服务端建议实现重试 / 退避结合源码文档可补充两点实操提示CPU 上限对应 durable-objects/gotchas.md 中的CPU time max 300s vialimits.cpu_ms超过默认 30s 的请求应主动调大或分块处理而 ~1000 req/s 是单实例软限吞吐要求更高时应参照该文档的Sharding分片思路将负载分散到多个 DO 实例。三、最佳实践清单3.1 状态管理State Management始终用不可变更新setState({...this.state, key: newValue})周期性裁剪无界数组消息、日志避免存储与内存膨胀大数据放 SQL不要塞进状态——状态保存在内存与存储中远超 SQL 合适负载的数据会拖垮实例128MB 内存上限。3.2 SQL 使用SQL Usage建表放在onStart()不要在onRequest()里建——onStart()每次实例初始化/唤醒都会执行保证表结构就绪且幂等api.md 中onStart()即用于CREATE TABLE IF NOT EXISTS使用参数化查询sqlWHERE id ${id}而不是sqlWHERE id ${id}为高频查询列建索引配合 100 列/2MB 行限制做好 schema 设计。3.3 调度Scheduling用await this.getSchedules()监控调度数量完成任务后主动cancelSchedule(scheduleId)取消保持在 1000 上限以内周期任务用 cron 字符串如0 0 * * *一次性任务用 Date 或秒级延迟api.md 调度示例。3.4 WebSocket始终在onConnect()中调用conn.accept()优雅处理客户端断开监听断开事件清理conn相关状态广播时高效遍历this.connections避免在循环内做重操作patterns.md 的聊天与游戏广播均为this.connections.forEach(c c.send(...))模式。3.5 AI 集成AI Integration聊天界面优先用AIChatAgent——自动流式输出、消息历史管理与断线恢复开箱即用裁剪消息历史以规避 token 与配额限制对应 1.2 节用 try/catch 降级响应处理 AI 错误对应 1.6 节需要缓存/路由时叠加 AI Gateway 配置configuration.md AI Gateway 一节。3.6 生产部署Production Deployment限流高流量 Agent1000 req/s实现请求节流避免打满单实例吞吐监控记录关键错误日志跟踪调度数量与存储用量getSchedules()、存储配额 10GB优雅降级AI 服务中断时给出可用的 fallback对应 1.6 节消息裁剪在AIChatAgent中强制执行最大历史长度如 100 条MCP 可靠性休眠后重新注册服务器对应 1.9 节并对 MCP 请求实现重试逻辑。四、故障排查决策要点速记把以上内容浓缩为上线前 checklist所有setState都是不可变更新状态里不放超大对象消息历史有硬性上限SQL 全部参数化表在onStart()建WebSocket 一律accept()MCP 服务器在onStart()幂等重注册调度任务做完成即取消超过 800 条告警callable返回值保证 JSON 可序列化AI 调用包 try/catch 并给 fallback必要时走 AI Gatewaywrangler.jsonc 的 DO 绑定class_name与代码类名、migrations 三者对齐对照第二节配额表做容量估算CPU 30s/300s、内存 128MB、存储 10GB、调度 1000、WebSocket 消息 32MiB。延伸阅读完整 API 与生命周期钩子见 agents-sdk/api.md项目初始化与 wrangler 路由、邮箱路由、AI Gateway、MCP 配置见 agents-sdk/configuration.md聊天工具、任务队列、邮件 AI 处理、实时协作等完整示例见 agents-sdk/patterns.md关于 Durable Objects 底层的休眠、迁移、并发与限额细节可参考 durable-objects/gotchas.md。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考