Agent 输出错了,你去翻日志。第 8 步的工具调用参数是空的,看起来就是罪魁祸首。于是加一段校验,重跑,错误换了个样子回来了——这次是第 5 步取回的检索结果根本没包含需要的那条记录,第 8 步只是空参数的下游反应。这一类误判在多步 Agent 里非常普遍:最早出错的那一步和后来越伤的那一步,通常不在同一处。
因果追踪要回答的问题很朴素:这条轨迹从哪一步开始变成不可修复的。
普通 trace 为什么不够
把 LangSmith、LangFuse 或者 OpenTelemetry 的 trace 打开,你能看到每一次 LLM 调用、每一次工具调用、每一段耗时以及 token 消耗。这解决的是“发生了什么”,不解决“哪里错了”。原因是 Agent 的失败大多是语义级的:HTTP 200 的响应里可以夹着编造的事实;参数类型完全合法的工具调用,可能对应一次本该走查询 A 却走了删除 B 的决策;每一个动作都成功,顺序错了,结果就废了。这些都不会出现在错误率曲线或者延迟仪表盘上。
tianpan.co 那篇讲 Agent 系统化调试的文章给了一个判断:延迟和错误率守在设施层,语义上的错误只能在轨迹层解决。这个区分很关键。很多人把 Agent 日志接进 Datadog 就觉得完事,那套工具擅长拆 P99、拆错误码,对它看不见的语义错误无能为力。
第一步:把轨迹变成可比对的结构
结构化追踪的前提是每类操作都是一条规范化的 span。OpenTelemetry 的 GenAI 语义约定给了一套公用属性名,包括 gen_ai.system、gen_ai.request.model、gen_ai.usage.input_tokens、gen_ai.usage.output_tokens,再加上工具特定的扩展字段。不同框架都按同一套模式打点之后,分析工具才可能跨架构复用。
比属性名更容易被忽略的是步骤级的 schema 归一化。LLM 的推理输出、工具调用请求、工具返回、最终回答,这几类东西在原始日志里长相完全不同:字段名不同、嵌套深度不同、有些存 JSON 有些存字符串。归一化要做的是把它们压成同构的步骤序列,每一步至少含类型、输入、输出、工具签名。这一步枯燥但必做,因为后面所有自动检查都建立在它上面。
成本要算清楚。完整记录每一步的输入输出,token 量会上去,尤其是把检索回来的几万字原文全存下来。实践中比较可行的账是:每一步存输入输出的哈希值,用于检测异常漂移;只对失败的轨迹保留完整内容。换句话说,全量存的是指纹,按需存的是原文。回放能力靠后者撑,成本靠前者控。
第二步:用约束把“对错”写成代码
有了归一化轨迹,就可以写可执行约束(executable constraints)。它们有两个来源,都算便宜。
- 工具模式:每个工具都有签名,参数该和声明的类型匹配,必填字段该存在,返回值该符合文档格式。这部分几乎能从现有的 schema 定义里自动生成。
- 领域策略:业务或流程层面的不变量。“下单前必须查过库存”“单次交易只允许调一次支付接口”。这类约束很难穷举,但即使只写出已知的那几条,也能拦住相当一部分实际事故。
约束逐步骤跑一遍,产出的东西叫证据日志(evidence log):哪个约束在哪一步被满足了或被违反了,违反时那个参数具体取什么值。它的价值在于把“读两百行日志猜”变成“直接看到第几步、哪个字段、什么值”。这一步的工程量不大,但偷懒不做,后面就无法自动化。
字节跳动那套工具设计建议里提到,工具在出错时应该返回结构化错误,包含 error 和 recovery_suggestion,让 Agent 有机会调整策略继续,而不是直接抛异常断了链路。这个做法对追踪是双重的:它让 Agent 继续跑,产生更完整的轨迹;同时这些结构化错误天然就是约束检查的一等信息源。
第三步:区分“最早变坏”和“最先报错”
证据日志解决的是局部对错。真正的难点在依赖关系:Agent 可能在第 3 步编造了一条信息,第 8 步的护栏才被触发。导致失败的是第 3 步,呈现失败的是第 8 步。找到轨迹“变得不可修复”的最早时刻,才是调度的核心目标。
一种被验证过的做法是把证据日志而不是原始日志送进第二次 LLM 推理。这里不是让模型自由发挥猜原因,而是让它基于已经结构化、带证据的步骤摘要判断因果链:哪一次违反导致了后续的违反,修正哪一步能走向一条成功的轨迹。研究里的对比结果值得记住——相比让模型直接读原始 trace 找错误,基于证据日志的做法在故障定位准确率上高出约 24 个百分点。差别不在模型,在输入的形态:给它一段经过验证的步骤摘要,比给它两百行异构日志有效得多。
这也解释了为什么中间步骤的完整度和约束标签的质量,直接决定了二次推理产出东西的质量。上游只要自己补全因果,这套就退化成又一个“让模型猜”。
故障分类法值得先建起来,再谈自动化检测
文献总结出的生产故障大致归为九类:计划执行偏离、信息捏造、无效工具调用、误读工具输出、意图与计划不匹配、用户意图不清、请求超出能力边界、安全护栏拦截、系统故障(超时、限流、API 报错)。前两类最常见也最难让机器判:它们要理解意图,不是检查语法。
这对工程的含义是不该指望一套规则把所有失败都抓出来。可行做法是先给失败轨迹打两类标签:故障类别、识别出的关键故障步骤。这些标签回流成标注数据集,既是指标也是回归基线。上线前对着这批已知故障回放,确认旧问题修掉了、新约束没被违反。
腾讯云那篇讲 Agent 可观测性的文章从另一个角度落到同一个问题上:执行 50 步之后,如何快速定位哪一步出了问题。不搭出步骤级的取证能力,这个问题的答案只会是“全量重跑,再猜一遍”。tianpan.co 引用的数据也值得看一眼:2026 年初有约 89% 在生产里跑 Agent 的团队上了某种可观测性,但只有约 52% 有验证行为质量的评估流水线。中间那约 50 个百分点的缺口,正是故障能潜伏的地方。
在代码层的几件具体事
OpenHands 的 V1 里这套设计落在“动作 → 执行 → 观察”三层上:LLM 生成的 JSON 工具调用先过 Pydantic 校验变成标准 Action 对象,ToolExecutor 执行,Observation 再把结果按模型能理解的结构化格式回传。这个分层的价值不止是可靠,还让每一步都有统一点:有动作记录,有执行记录,有观察记录。要让 ToolCallMetadata 里带上 tool_call_id、function_name、命中的工具列表长度,因果关联就一定错不了。
另一件事是工具失败时返回什么。返回空字符串是下策,因为模型无从判断是“查了没有”还是“调用失败了”,两种情况的处理策略完全不同。返回截断内容要带上明确的标记,否则 Agent 会以为这是全量。像知乎那篇讲工具坑位里引用的超时包装代码,返回 {"role": "tool", "tool_call_id": ..., "content": "工具调用超时,请稍后重试"},看着够用了,但真要用来做因果分析,这条记录本身还得带上 span 属性和步数,不然你只知道某处超时了,不知道它把后面几步带去了哪。
把这些拢到一起,产出的调试循环并不复杂:按规范化结构记录每条轨迹;自动跑约束检查并标出带证据的违反;给失败轨迹打上故障类别和关键故障步骤;把这些标签喂进评估流水线,形成不断生长的标注集;部署前回放它,验证已知故障修好且没引入新的违反。这套东西不漂亮,工作量集中在日志结构的耐心和约束的持续维护上。但它是一条轨迹从“又要猜一遍”变成“可以直接指出那一步”的分界线。
Agent 调试的困难根子在于概率性加有状态加长跨度,这一点不会因为换个更强的模型就消失。等模型变聪明是最被动的方案;让失败变得可见,才是工程师手里真正能控的那一半。
转载请注明出处: 皮哈皮阿
本文的链接地址: https://blog.phpat.com/ai-dev/700.html
微信或手机浏览器扫一扫,随时随地随心阅读与分享
-
上下文工程:从 Prompt 到 Context 的工程化实践
客服 Agent 答错时,团队第一反应是换模型。把那次请求的上下文打印出来才发现,模型看到的是一份过期政策、两份互相矛盾的条款,还有一长串无关日志。上下文工程要解决的,就是这类问题。
2026/10/06
-
RAG 的下一站:Agentic Retrieval
用户问“我们去年买的套餐现在还能退吗”,经典 RAG 检索出一段通用退款政策就结束了。可这个问题至少要拆成订单时间、地区、套餐版本三件事。Agentic Retrieval 要解决的,就是这种“一次检索不够用”的场景。
2026/10/12
-
推理模型输出被截断后怎么接回去
推理模型遇到输出截断,重试整条请求代价高;续写也有隐藏门槛。从识别边界、提示回灌到 prefill 与成本判断,聊聊工程上怎么做才不算亏。
2026/10/25
-
约束解码让 JSON 不再崩,但它会改坏推理
约束解码让 JSON 解析失败率归零,工程师可以删掉一堆重试和修复代码。但它会挤占模型的推理预算:强制格式在部分任务上带来10%以上的准确率下降。文章梳理 OpenAI、Anthropic、Gemini 和其他自托管引擎的现状,以及 schema 设计、两阶段模式与编译缓存几个实操要点。
2026/10/22
-
Agent 上下文压缩:四层策略与失败代价
把 Claude Code 的四段分层与 Hermes Agent 的双阈值压缩系统并排看重:200K 窗口下的 50%/85%、legacy 与 lean 尾部的实测差池、未处理到的摘要模型窗口溢出,以及工具对配对边界为什么是能不能跑的问题。
2026/10/23
-
推理模型的并行思维链采样怎么用才不亏
并行思维链采样的成本不是白花的。结合推理模型测试时计算的几条实证结论,梳理best-of-N、束搜索、自洽性投票和自我修订在什么场景下划算、什么场景下只是在烧钱。
2026/10/26
京公网安备11011402053654 
@muffin:链接已更新,分类图像功能...
AI网址导航模版图标库更换指南
作者大大,图标库邀请链接失效了,麻烦更新...
AI网址导航模版图标库更换指南
太好看了,快点更新!
友情链接
@戴墨镜的刘备:哈喽,路过点赞。
vue.js组件之手写签名板vue-signature-simple
太好看了,快点更新!太棒了!👍真的很赞!
vue.js组件之手写签名板vue-signature-simple
你写得非常清晰明了,让我很容易理解你的观...
Emlog插件RSS订阅器发布