智能体调试实战：从日志、追踪到回放复现的排错闭环

普通程序出错，看堆栈就能定位；智能体出错，可能是模型选错了工具、提示词理解偏了、或者工具返回了意外格式。这种「非确定性」让调试更像破案。本文给出一套从日志、追踪到回放复现的排错闭环，把玄学变成可复现的工程问题。

智能体为什么难调试

传统程序的执行路径是确定的：输入 A 必走分支 B 。智能体的路径由模型在运行时「临场决定」，同样的输入两次可能走不同工具、产出不同结果。错误因此散落在三个地方：模型的理解、提示词的设计、工具的返回。没有单一堆栈能同时覆盖这三者，所以调试要从「看一行报错」升级为「重建整个决策过程」。这与 智能体可观测性 强调的 trace 思路一脉相承。

第一层：把每一步都打日志

最低成本的改进是记录。每一次模型的输入与输出、每一次工具调用的参数与返回、每一轮耗时，都落盘成结构化日志。哪怕成功也留摘要——成功的轨迹是未来对比失败样本的基线。日志要包含关键信息但不喧宾夺主，关于工具该暴露什么、藏什么，智能体工具设计实践 给了具体规范。

第二层：用 trace 看清链路

单次对话往往跨多轮、调多个工具，零散日志看不出因果。给一次会话分配一个 trace_id，把所有相关日志串联成一条链路，就能看清「模型为什么在这个节点选了那个工具」。把 trace 可视化成时间线，瓶颈和异常分支一目了然。这层是定位「非确定性」错误的主战场。

第三层：回放与最小化复现

看到异常后，最有力的一步是复现。把失败那次的输入（含上下文、工具状态）原样重跑，观察是模型变差、提示词歧义还是工具返回异常。能复现，就能量化；能最小化到单一变量，就能定位根因。回放不必每次全量，先缩小到触发失败的那个最小片段。

把失败变成测试集

每个复现出来的失败，都是一份免费的高质量用例。把它存进回归集，下次改提示词或换模型时一键跑，防止同类问题复发。久而久之，你的智能体就有了属于自己的「单元测试」，可靠性靠积累而非运气。这和 智能体护栏实现 里「把防护沉淀为规则」的取向一致。

常见症状对照表

• 一直调同一个工具：多半是工具返回没给「完成信号」，模型以为还没做完，加明确的终止语义即可。
• 工具调用格式错：模型产出的参数不符合 schema，需在客户端加校验并回写错误让模型修正。
• 中途跑题：提示词缺少约束或上下文被截断，缩短无关历史、强化目标指令。
• 偶发失败：典型的非确定性，靠回放复现 + 回归集锁定，而非凭印象改。

调试智能体不是更玄，而是更系统。日志给证据、 trace 给因果、回放给复现、回归集给保障——四件武器备齐，非确定性就不再是借口。把这套基座搭好，再去接 企业系统 API 这类复杂外部依赖时，你才有底气说「出问题我知道去哪看」。

常见问题