本文是《AI Agent 实战》系列第 4 篇。前三篇我们从概念讲到 LangGraph、再到 Dify每篇末尾都有常见报错小节评论区问得最多的反而是报错太长了能不能给一张能直接照着查的表这篇就是那张表。建议收藏报错时按层定位别再盲改代码反复试错。写在前面先建立一个分层心智模型Agent 报错最让人崩溃的不是错误本身而是你不知道该去查哪一层。一个 Agent 请求的完整链路是你的业务代码 / Dify 应用 ↓ 编排框架层LangGraph 状态图 / Dify 工作流 ↓ 模型 API 层DeepSeek / 通义 / Kimi / OpenAI 兼容端点 ↓ 工具层搜索 API、数据库、本地文件、内部服务四层里任何一层出错最后都可能表现为程序崩了/没结果/答非所问。排查的第一原则是先分层定位用一句最简单的固定输入测试——能跑通就一层层往下加哪一步炸了就是哪一层的问题。本篇按层给你三张排查表最后给一套通用的四步调试方法论。所有口径基于 2026 年的 LangGraph 1.x / Dify 1.x / 主流国产模型 API。一、模型 API 层最常见的四类报错这一层的报错有明确的 HTTP 状态码定位最快。表 1模型 API 报错速查现象原因解法401 Unauthorized/ invalid api key密钥错误、过期、复制时带了空格换行或鉴权头用错Authorization: Bearervs 自定义头重新复制密钥确认环境变量没被引号污染确认该端点要求的鉴权头格式403 ForbiddenIP 不在白名单、地区不支持、账号无该模型权限检查平台控制台的地域/IP 限制换合规出口429 Too Many Requests/ rate limit超出 RPM每分钟请求数、TPM每分钟 token 数任一维度或短时间请求量激增触发增速保护先读响应头的retry-after按其等待重试必须用指数退避 随机抖动见下文代码400 context length exceeded/maximum context length is X tokens系统提示 历史消息 当前输入总 token 超过窗口上限裁剪历史保近删远、摘要压缩、改用 RAG 检索片段替代全文注入客户端加预校验402/ 额度不足账号余额耗尽、支付方式失效充值或换 key生产环境加额度预警5xx/ 连接超时 / 响应卡住服务端抖动或网络问题这类是可重试错误设置 15–30s 超时最多重试 2–3 次返回内容合规拦截如 406 / content policy输入或输出触发平台内容安全策略检查提示词里是否带入敏感词给用户侧兜底话术两个新手最常犯的错把 429 当网络问题无限快速重试。429 是配额维度超了RPM/TPM 是多维度的任一超了都报 429快速重试只会加重限流。正确姿势import random, time def call_with_backoff(fn, max_retries4): for i in range(max_retries): try: return fn() except Exception as e: status getattr(e, status_code, None) if status 429: # 优先尊重服务端指示 wait float(getattr(e, retry_after, 2 ** i)) elif status and 500 status 600: # 服务端抖动可重试 wait 2 ** i else: raise # 400/401 这类重试没用直接抛 time.sleep(wait random.uniform(0, 1)) # 随机抖动防重试风暴 raise RuntimeError(重试次数耗尽)上下文超限不预检多轮对话把每轮消息无脑 appendToken 近似线性增长迟早撞墙——而且撞墙前越聊越笨早期无关信息干扰模型。对策滑动窗口保最近 N 轮 更早内容做摘要代码里调用前用tiktoken或平台计费接口预估 token。二、LangGraph 层状态图的六类典型报错框架层的报错信息通常更哲学直接看字面很难懂。逐个拆表 2LangGraph 报错速查报错原文关键词本质原因解法GraphRecursionError: Recursion limit of 25 reached图执行超过最大超步数默认 25。要么真的存在死循环要么任务本身就长先查条件边是否每条路径都能到达 END确认逻辑正确后调用时传{recursion_limit: 50}Agent 任务务必在业务层加最大步数兜底InvalidUpdateError: Must write to at least one of [...]节点返回的 key 不在 State schema 里拼写错误最常见或返回了空更新检查节点返回 dict 的 key 与 TypedDict 字段逐字对齐不更新任何字段就返回{}别返回无关字段INVALID_CONCURRENT_GRAPH_UPDATE两个并行节点在同一超步写同一个字段而该字段没配 reducer。LangGraph 宁可崩溃也不静默丢数据给并发写入的字段加Annotated[list, operator.add]或自定义合并函数这是设计哲学不是 bug状态丢了并行跑完只剩一个节点的结果同上后写覆盖先写Last-Write-Wins排查所有可能被并行写入的字段全部显式声明 reducer加了 Checkpointer 后恢复运行改过的 state 不生效旧检查点还记着图走到哪了update_state后它仍从旧位置继续先清掉该thread_id的检查点数据或换新 thread_id再重新 invoke子图/嵌套图运行后状态丢失或类型报错父子图 State schema 字段类型不一致返回值没对齐通道定义统一用同一份 State 定义dataclass/TypedDict 共享子图返回只写父图认识的字段另外三个不报错但结果不对的隐性问题Agent 无限循环不结束模型反复调同一个工具。查提示词里是否缺少够了就停止的判断依据查工具返回是否每次都一样死板的工具会让模型以为没执行成功业务层强制最大迭代次数。工具从没被调用过tool_calls为空模型或端点不支持 function calling或工具 docstring 写得太含糊模型不知道何时调用。确认模型的兼容模式把 docstring 改成当用户问 X 时使用本工具这类触发式描述。中断恢复后行为诡异interrupt 之后传Command(resume...)的值类型要和中断前抛出的期望一致用错 thread_id 会串到别的会话状态——生产环境 thread_id 必须和业务会话一一对应。三、Dify 层知识库问答的七个高频坑低代码平台不报错它报效果不对。对照第 3 篇的实战把高频问题做成表表 3Dify 排错速查现象最可能原因定位动作 / 解法明明文档里有答案却说不知道检索没召回分段切断语义 / 阈值过高用知识库召回测试输入原文关键词召回不到→调分段策略技术文档 300–500 token、重叠 10%–20%召回到了还答不了→提示词约束或模型问题答案把两份文档内容混着说多文档相似片段交叉文档打元数据标签按标签过滤或拆分知识库提示词强制仅依据上下文表格/参数/价格答错表格按纯文本切碎行列关系丢失关键表格转问答对模式入库要求价格保修类逐字引用原文默认分块策略上线后效果平平默认策略不适配技术文档按标题层级切分合同保结构论文保段落完整回答很慢Rerank 延迟 串行节点 Top-K 过大Top-K 收敛到 3–5无依赖节点并行高频问题开结果缓存本地部署容器起不来 / OOM宿主机资源不足默认栈多容器至少 4 核 8G内存紧张时精简向量库配置换 embedding 模型后检索更差了只改了配置旧文档没重建索引换嵌入模型必须整库重新索引否则新旧向量不在同一空间Dify 排查的核心手段就是召回测试它能直接告诉你检索层和生成层谁在背锅。这一步跳过后面全是玄学调参。四、工具层的两类经典故障工具执行成功但模型不认账工具返回了大段 JSON/HTML 原文模型消化不了。解法工具返回值先做裁剪和结构化只回结论字段、限制长度别让工具把整个网页塞回上下文——这也是 Token 爆炸的隐形来源。工具报错把整个图拖崩外部 API 5xx、超时、参数错误都会从节点里往外抛。解法LangGraph 1.x 有原生支持给节点配重试策略RetryPolicy和超时图侧配error_handler做降级分支——网络抖动不该让整条流程崩掉。注意error_handler别配成静默吞错吞掉的错误是最难查的错误。五、通用调试方法论四步定位法比记错误消息更有价值的是固定流程稳定复现用最小固定输入在本地重现固定框架版本、模型、温度参数。复现不了的问题先别改代码。读执行轨迹LangGraph先看拓扑graph.get_graph().draw_mermaid()是否和设计一致用stream模式逐节点打印状态再深入就上LangSmith官方配套节点顺序、每次状态变更、工具调用、token 消耗全程可视化或 LangGraph StudioDify应用日志与标注里看每次对话的召回片段和节点执行记录模型 API打印原始请求体和响应体——90% 的框架 bug最后查出来是请求参数错了。收缩边界把出错的图切成最小子图逐个去掉工具、外部依赖、并行节点。问题跟着哪个组件走就是谁的锅。修改 回归改完必须用一组固定问题金标集哪怕只有 10 条重跑确认修复没把别的行为改坏。Agent 系统没有单元测试思维改一个提示词坏三个场景是常态。六、一张总图 应急顺序【图 1三层排查决策图——插入文件 图1-Agent报错三层排查决策图.png】遇到任何报错按这个顺序过一遍10 分钟内大概率定位有 HTTP 状态码 → 是 → 查表 1API 层 → 否 ↓ 用的 LangGraph → 是 → 异常类型对表 2状态/reducer/递归/检查点 → 否 ↓ 用的 Dify → 是 → 先跑召回测试再对表 3 → 否 → 直接看工具返回值和原始请求体第四节七、成本与预防别让报错白烧钱说个容易被忽略的点死循环类故障是烧钱大户。一个没有最大步数兜底的循环 Agent一晚上能把账号余额跑光社区里真实发生过。三件套必须默认配业务层最大迭代次数 / 最大子任务数每次调用的 token 预算检查超限熔断返回部分结果平台侧余额/用量告警多数模型平台支持开。这些机制本身不贵配置各几行代码但能把事故降级成日志里一行警告。总结本篇给了你三张分层排查表API 层看状态码、LangGraph 层看异常类型、Dify 层先跑召回测试、一套四步调试方法论、一个防烧钱三件套。把它当字典用出问题时顺着分层往下查不要凭感觉改代码。下一篇预告《如何把 Agent 接入微信 / 飞书 / 企业微信》——Agent 搭好了怎么让它真正被用户用起来消息回调、鉴权、限流一次讲清。评论区回复排查领取本篇三张表的高清打印版A4 单页。也欢迎贴你遇到的报错原文我会挑典型的在下一篇统一解答。