loading

Loading

探索与发现

首页 AI 开发实战

Agent 工具调用链的因果追踪:找到那个不可修复的步骤

字数: (3264)
阅读: (5)
0
摘要:从步骤级归一化到证据日志,再到区分“最早出错”和“最先报错”,拆解工厂级的 Agent 工具调用链追踪怎么做、贵在哪、哪些只能人工补。

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

手机扫码阅读

微信或手机浏览器扫一扫,随时随地随心阅读与分享

您可能对以下文章感兴趣
1 / 1
预览图