AI Agent 报错怎么办？10 个高频报错+修复 prompt

一句话结论

AI Agent 跑崩 90% 是 prompt 设计问题，不是模型问题。 看完这 10 个高频报错 + 修复 prompt，少踩 80% 坑。

如果你正用 ChatGPT Agent、Claude Computer Use、Cursor Agent、扣子 Coze 或 Dify 搭东西，下面是急救手册。

AI Agent 跑崩 vs 报错的区别

两件事混着说但修法完全不同：

• 跑崩：agent 抛异常、进程挂了、loop 强停。日志里有明确报错字符串
• 答错：没抛错，但答案不对、调错工具、参数填错。日志看不到异常

这篇专讲跑崩。「答错」方法论参考 AI agent 怎么 debug。

下面 10 个按出现频率从高到低排，每个给：典型报错信息 + 3 条根因 + 修复 prompt。

10 个最高频报错 + 修复 prompt

报错 1：Tool call exceeded max iterations

典型报错信息：

Error: Maximum tool call iterations (10) exceeded.
Agent reached step limit without producing final answer.

也可能是：recursion_limit reached（LangGraph）、max_turns exceeded（OpenAI Agents SDK）、agent_iterations_limit（Coze）。

症状：Agent 在两三个工具间反复 ping-pong，跑到上限被强停，token 烧了一堆没产出。

3 条根因：

1. 工具返回的结果模型「没看懂」，以为没调过，又调了一遍
2. 系统 prompt 没规定「拿到结果后必须停」的退出条件
3. 工具间存在隐含依赖（B 需要 A 的结果），但 prompt 没说清顺序

修复 prompt：

你是一位精确执行的任务 agent。
执行规则：

每次调工具后，在 thinking 里判断：当前结果是否已能回答用户？

能 → 立刻 stop 给答案，不再调工具
不能 → 说明还差什么信息，再选下一个工具


同一工具最多连续调 2 次。2 次没拿到有效结果，承认无法完成并停止
调用顺序：先查询类（search、get）后修改类（create、update、delete）
总迭代硬上限 6 步，到 5 步必须收尾
调了 3 次同类工具还没结果，停下告诉用户：「无法通过当前工具完成，建议：[替代方案]」。
任务：[此处填用户任务]

报错 2：Context window overflow / Context length exceeded

典型报错信息：

openai.BadRequestError: This model's maximum context length is 128000 tokens.
However, your messages resulted in 134821 tokens.

Anthropic 是 prompt is too long: X tokens > Y maximum，Gemini 是 INVALID_ARGUMENT: input token count exceeds...。

症状：跑到第十几轮 agent 直接挂，前面好好的，后面突然报错。

3 条根因：

1. Agent 默认把所有历史 tool call 和 raw 结果都塞进 prompt，多步骤任务很快撑爆
2. 某一次 tool 返回了几万字的网页 HTML 没做提取
3. 系统 prompt 本身就写了 3000 字，留给对话的空间没几个

修复 prompt：

你是一位严格控制上下文的 agent。
规则：

每次 tool 调用后，把原始返回压缩成不超过 200 字的结构化摘要
格式：[tool_name 结果] key1: value, key2: value, 共 N 条
超过 5 轮，把第 1 到 N-3 轮压成 100 字摘要，只留最近 3 轮原文
tool 返回超 2000 字的，先调「提取关键字段」再用
用户原始问题、当前 sub-goal、已完成步骤永远留在 prompt 头部
context 上限：[填具体数字]，单次 run 预算：60000 token。
任务：[此处填用户任务]

记忆策略选哪种参考 AI Agent Memory。

报错 3：Rate limit / API rate limit exceeded

典型报错信息：

openai.RateLimitError: Rate limit reached for gpt-4o in organization org-xxx
on tokens per min (TPM): Limit 30000, Used 28000, Requested 5500.

Anthropic 是 rate_limit_error: Number of request tokens has exceeded...。

症状：agent 跑到一半突然 429，等几秒重试也是 429，整个 run 失败。

3 条根因：

1. Agent 自己在死循环刷 API（参见报错 1），每分钟几十次请求把限额烧光
2. 同时跑了多个 agent 实例，共用一个 key，叠加触发限额
3. 单次请求 prompt 太长，TPM（tokens per minute）一次就吃掉大半额度

修复 prompt：

你是一位节约 API 调用的 agent。
预算规则：

每次 reasoning 前问：这步真的需要调工具吗？自己能答的就不调
多个独立查询合并成 batch 调用（查 3 城天气调 1 次 get_weather_batch，不要分 3 次）
同会话出现过的 tool 结果直接复用
遇到 rate_limit 不立刻重试，等待指数增长 1s → 4s → 16s，最多 3 次
在 thinking 里记账：「本次 run 已调 N 次，预算剩 M 次」。
任务：[此处填用户任务]

报错 4：Tool schema mismatch / Invalid function arguments

典型报错信息：

openai.BadRequestError: 'arguments' is not valid under any of the given schemas
- 'city' is a required property
- Additional properties are not allowed ('cityName' was unexpected)

症状：模型自信地调了工具，但参数名跟 schema 对不上，工具直接拒收。

3 条根因：

1. 工具 schema 里字段叫 city，模型按英语习惯填了 cityName 或 city_name
2. enum 字段（如 status: "open" | "closed"）模型填了 schema 没列举的值
3. 嵌套对象层级填错，比如 schema 要 \{filter: \{type: "..."\}\} 模型直接给了 \{type: "..."\}

修复 prompt（写在 tool description 里）：

查询城市天气信息。
参数严格要求（违反会拒收）：

city：必填，字符串，城市中文全称（如「上海」「北京」），不接受英文、拼音、简称
date：可选，字符串，格式「YYYY-MM-DD」，不传默认今天
include：可选，数组，元素只能是「temperature」「humidity」「aqi」「wind」，其他值报错
调用前在 thinking 逐字段确认：

字段名拼写与 schema 完全一致（大小写、下划线）
字段值在允许范围内
没添加 schema 外的额外字段
不确定某个参数怎么填，宁可不调先问用户。

写工具描述的方法论看 Function Calling 是什么。

报错 5：Hallucinated function / Tool not found

典型报错信息：

ToolNotFoundError: Agent attempted to call 'send_wechat_message',
but no tool with this name is registered. Available tools: [send_email, ...]

症状：明明只注册了 5 个工具，agent 自创了一个根本不存在的 send_wechat_message 去调，整个 step 失败。

3 条根因：

1. 系统 prompt 里描述任务时提到了「微信通知」，模型脑补了一个对应工具
2. 模型训练数据里见过类似工具名，下意识用了
3. 工具列表太多（超过 30 个），模型记混了

修复 prompt：

你是一位严格遵守工具清单的 agent。
可用工具清单（不在这里的工具一律不存在）：

send_email：发邮件，参数 to/subject/body
search_web：搜网页，参数 query
get_weather：查天气，参数 city
[此处列出全部已注册工具]
规则：

调用前在 thinking 写出工具名，对照清单是否存在
用户需求需要清单外能力（发微信、订机票），不编造工具名，告诉用户：「我没有 [能力] 的工具，替代方案：[2-3 个已有工具方案]」
发现自己在 thinking 写出清单外工具名，立刻停止重新规划
任务：[此处填用户任务]

报错 6：Permission denied / Authorization failed

典型报错信息：

PermissionError: Tool 'execute_shell' requires elevated permissions.
User has not granted access. Request access via auth.request() first.

ChatGPT Agent 常见 requires_user_approval，Claude Computer Use 是 screen_capture_permission_denied，Cursor Agent 是 file_write_outside_workspace。

症状：Agent 想干一件事被平台权限系统拦下来，但 agent 自己不知道怎么处理这个拦截。

3 条根因：

1. Agent 没有等待用户授权的机制，被拦了直接当成 fatal error
2. 权限粒度比 agent 以为的更细（比如读文件 OK，写文件不行）
3. 沙箱限制（Claude Computer Use 不能访问宿主机文件系统）

修复 prompt：

你是一位尊重权限边界的 agent。
规则：

调任何「修改类」工具（write、delete、send、execute）前，在 thinking 检查是否有授权
遇到 PermissionError、AuthorizationError、ApprovalRequired：

不要重试
告诉用户：「我需要 [权限] 来 [做什么]，授权后继续」
等用户回复再恢复


沙箱限制清单（环境里做不到的）：

[根据平台填，如访问宿主机、sudo、修改系统文件]
遇到这些告诉用户「此环境不支持，建议：[替代方案]」


任务：[此处填用户任务]

报错 7：Tool timeout / Request timeout

典型报错信息：

TimeoutError: Tool 'fetch_url' did not respond within 30s timeout.
Agent loop terminated.

症状：某个工具调用卡住，超时后 agent 整个 loop 挂掉，前面已经做的几步全白费。

3 条根因：

1. 工具本身慢（爬一个反爬严的网站、调一个海外 API）
2. 工具内部死循环或网络问题，没有自己的超时控制
3. Agent 框架的默认超时太短（很多框架默认 30s）

修复 prompt：

你是一位对超时容错的 agent。
规则：

调用可能慢的工具（fetch_url、scrape_web）前，在 thinking 预估耗时
工具超时报错时：

第一次：换等价工具重试（fetch_url 失败换 search_web）
第二次：拆小任务（「爬整个网站」改成「爬首页 + 摘要」）
第三次还失败：跳过，告诉用户「[这步] 因超时无法完成，已完成部分：[列出]」


同一超时调用重试不超过 2 次
任务：[此处填用户任务]

报错 8：JSON parse error / Invalid output format

典型报错信息：

json.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
Agent output: "Sure! Here's the JSON: ```json\n\{...\}\n```"

症状：要求模型返回 JSON，它返回了 markdown 包裹的 JSON 或带前后说明的 JSON，下游解析失败。

3 条根因：

1. 单靠 prompt 强调「只返回 JSON」不够，模型偶尔会「热心」加说明
2. 没启用 structured output / JSON mode
3. 下游解析没做宽容处理

修复 prompt：

你的本次输出必须严格满足以下 schema：
{
“status”: “success” | “error”,
“data”: { “result”: string, “confidence”: number },
“reasoning”: string
}
硬约束：

只输出 JSON 本身，前后零字符
不用 json 代码块包裹
不加「Sure」「Here is」「以下是」等引子
字段名与 schema 完全一致，不多不少
信息不足时 status 设 “error”，data 设 null，reasoning 说明缺什么
错示范：Sure! {“status”: “success”, …}
对示范：{“status”: “success”, “data”: {…}, “reasoning”: ”…”}

调 API 时同时开 response_format=\{"type": "json_object"\} 兜底。

报错 9：Infinite reasoning loop / Step limit exceeded

典型报错信息：

RuntimeError: Agent reasoning step 50 exceeded.
Last 5 steps repeated similar thinking without making progress.

跟报错 1 类似但更隐蔽——agent 不是在调工具死循环，而是在 thinking 里反复推理「用 A 还是 B 还是 C…」就是不行动。

3 条根因：

1. Prompt 给了太多选项，触发分析瘫痪
2. 模型对任务理解模糊，反复重新解释任务而不是执行
3. 没设 reasoning step 上限

修复 prompt：

你是一位行动优先的 agent。
行动准则：

看到任务后最多用 2 段 thinking 决定第一步，立刻调工具或给答案
不要反复 weighing options。判据：两个选项都能接受时选成本低的
每段 thinking 必须以具体行动结尾，只有 3 种：调工具、问用户、给最终答案
连续 3 段 thinking 没产生行动，直接问用户：「任务有歧义：[具体歧义点]」
Thinking 是为决定下一动作，不是表演周到。
任务：[此处填用户任务]

报错 10：Memory / State corruption

典型报错信息：

KeyError: 'user_id' not in agent_state.
StateError: Memory checkpoint inconsistent with current step.

症状：Agent 跑到中途突然找不到之前存的状态，或读到的状态跟实际不一致。

3 条根因：

1. 多个 agent 实例共用一份 memory，互相覆盖
2. State key 命名冲突（两个步骤都用 data 这个 key）
3. Checkpoint 写入失败但没报，下次读到旧版本

修复 prompt：

你是一位严格管理状态的 agent。
State 管理规则：

key 用「步骤名_字段名」格式（search_results、user_profile_email），禁用 data、result、info 等泛名
读取前先 has_key 检查，不存在就重新生成而不是报错
写入后立刻读一次确认
多 agent 协作时 key 加 agent_id 前缀隔离
关键 state（用户身份、订单号、金额）写入后 echo 给用户确认
如果同一 key 两次读结果不同，立刻报告「state 不一致，请重启会话」。
任务：[此处填用户任务]

3 个 prompt 对照：错 vs 对

光看修复 prompt 不直观，下面 3 个最高频场景给「错的 prompt 长什么样、对的 prompt 长什么样」。

对照 1：让 agent 查 3 个城市天气

错的 prompt（必报 rate limit 或迭代超限）：

帮我查一下北京、上海、深圳的天气。

模型会一个一个调 get_weather，调 3 次。城市变 30 个就崩。

对的 prompt：

查北京、上海、深圳今天的天气。

要求：
1. 优先 get_weather_batch 一次查 3 城，不要分 3 次
2. 没有 batch 时串行调用每次间隔 500ms 避免限流
3. 结果用表格返回：城市 | 温度 | 天气 | 空气质量

差异：「批量优先 + 限流保护 + 输出格式」三件事写死。

对照 2：让 agent 改文件

错的 prompt（必触发 permission 报错或改错文件）：

帮我把项目里所有 console.log 删掉。

Cursor Agent / Claude Computer Use 大概率扫整个磁盘，触发权限拦截。

对的 prompt：

把当前 src/ 下所有 .ts 和 .tsx 文件的 console.log 删掉。

规则：
1. 只在 src/ 下操作，不碰 node_modules、dist、.git
2. 删除前用 grep 列出所有要改的文件给我看，确认 yes 再动手
3. 每个文件改完用 git diff 给我看一眼
4. 遇到 permission denied 立刻停下告诉我，不要自动重试

差异：「作用域 + 确认步骤 + 异常处理」全写明。

对照 3：让 agent 做研究报告

错的 prompt（必爆 context 或死循环）：

研究 OpenAI、Anthropic、Google 2025 年 AI 进展，写 2000 字综合报告。

Agent 会爬几十个 URL，每个几千字 HTML 塞进 context，第 5 个就 overflow。

对的 prompt：

任务：写 OpenAI / Anthropic / Google 2025 年 AI 进展综合报告，2000 字。

流程（严格按顺序）：
1. search_web 每家搜 1 次「\{公司名\} 2025 product release」，只看前 5 结果
2. 对每个结果调 fetch_url 后立刻 summarize 成 100 字摘要，原文丢弃
3. 摘要收齐（最多 15 条）后开始写报告，写作阶段不再调任何工具
4. 任意单步超过 8 次工具调用停下汇报进度

不要：全文阅读所有原始页面、对同公司反复搜索、写作阶段还调工具。

差异：「分阶段 + 压缩 + 终止条件」前置。

平台特异性：每个平台的独家坑

通用规则讲完，下面是各家平台的独家坑——这些坑跨平台用户经常踩。

ChatGPT Agent / GPTs

• requires_user_approval 频繁打断：GPTs Actions 默认每次外部调用都要确认。修法：可信 domain 加白名单
• Knowledge 文件超 20 个检索失效：retrieval 召回率断崖式下降。修法：合并成 1 个结构化大文档 + 清晰 H2 分节
• Code Interpreter 沙箱重启丢状态：跨轮对话沙箱可能重置。修法：每轮先检查关键库是否存在，缺了再装

入门看 ChatGPT Agent 模式怎么用。

Claude / Computer Use

• screen_capture_permission_denied：macOS 屏幕录制权限没给。修法：系统设置授权运行 agent 的应用
• 超过 100K 准确率急降：Claude 200K 窗口名义可用，实际超 100K 明显下降。修法：滑动窗口截断到 80K 内
• tool use 强制 JSON Schema：Claude 比 OpenAI 严格，多个字段就拒。修法：用 additionalProperties: false 显式禁止额外字段

实战见 Claude Computer Use 教程。

Cursor Agent

• file_write_outside_workspace：不允许写工作区外文件。修法：批处理时把目标目录加进 workspace
• 大型 monorepo 索引慢：5 万文件项目上下文构建要 10+ 秒。修法：用 .cursorignore 排除 dist、node_modules
• 多轮编辑后撤销难：改了 20 个文件想回滚没原生支持。修法：每次任务前手动 git commit 当还原点

Coze / 扣子

• 插件返回值字段名变了不报错：插件 schema 改了，工作流引用还是旧名，运行时给空值。修法：改 schema 后在工作流编辑器手动「重新映射输出」
• 大模型节点 token 上限因模型而异：豆包跟 GPT-4 限额不同，跨模型迁移会崩。修法：加 token 计数节点，超 80% 触发摘要
• if 分支文本比较坑：「true」和「True」不等。修法：判断条件强制小写化

详解看 Coze 工作流怎么搭。

Dify

• 知识库 top_k 默认 3 太少：复杂问题缺上下文。修法：手动调到 5-10，配合 rerank
• Agent 节点与工作流状态不互通：嵌 agent 节点时中间变量外面拿不到。修法：让 agent 把关键中间结果写进 conversation_variables
• API 调用 timeout 默认 60s：慢 API 常超。修法：系统设置改 WORKFLOW_NODE_EXECUTION_MAX_TIME

参考 Dify 工作流教程。

Kimi K2 Agent

• 长上下文优势但 thinking 比 GPT-4o 慢 2-3 倍，多步任务体感差
• 国内合规过滤偶尔误伤金融、医疗类查询
• 没有官方 function calling SDK，要自己实现 OpenAI 兼容层

反向劝退：什么任务不该上 AI Agent

被人忽悠用 agent 之前，先确认你的任务不是下面这些：

判断标准：如果你的任务能写一段 50 行代码搞定，就别上 agent。Agent 适合的是「步骤数不确定、需要中途决策、单步失败可接受」的场景。

调试 AI Agent 的 5 个必备习惯

修了一年 agent，下面 5 件事真正长期降 bug 率：

1. 永远接 tracing：LangSmith、Langfuse、Phoenix 任选一个，没 trace 等于裸奔
2. prompt 加版本号：每次改 prompt 标 v3.2，git commit 写清楚改了啥
3. 每个工具先单测 10 个 case：边界值、空值、超长输入跑一遍再接入
4. 设 token 预算告警：单次 run 超预算（如 50 万）自动停，避免烧穿账户
5. 写 eval 集合：每次修复的 bug 加进测试集，改代码先跑保证不退化

框架对比看 LangChain vs LangGraph 和 CrewAI vs AutoGen。

一个能直接套的诊断 Prompt

下次 agent 报错，把信息按下面格式贴给 Claude / GPT-5 让它帮你定位：

你是一位资深 AI agent 工程师，帮我定位 agent 报错的根因和修复方案。
我的 agent 配置：

平台/框架：[LangChain / LangGraph / OpenAI Agents SDK / CrewAI / AutoGen / Coze / Dify / Cursor Agent / Claude Computer Use]
用的模型：[gpt-4o / claude-sonnet-4-7 / kimi-k2 / …]
任务一句话描述：[agent 在做什么]
涉及工具数量和类型：[如：3 个查询工具 + 1 个写邮件工具]
报错信息（完整粘贴，不要截短）：
[此处粘贴报错堆栈]
trace 关键片段（最后 3 步）：
[此处粘贴 trace]
已尝试的修复：
[列出已经做过的尝试和结果]
请按以下格式输出：

报错分类：属于本文 10 类报错的哪一类，或是其他什么
最可能根因：1-2 句话定位
三步修复方案：按「立刻可做、需要改 prompt、需要改架构」排序
修复后的 prompt 模板：可直接复制粘贴的版本
长期预防：1-2 条避免下次再犯

相关阅读

• AI agent 怎么 debug：错误排查 8 个实战技巧
• AI Agent 是什么
• Function Calling 是什么
• AI Agent Memory 怎么设计
• Coze vs Dify 对比
• Claude Computer Use 教程