简介:本文对比智能体出问题时两种常见排查思路:只看最终答案的"黑盒式"排错,与基于执行轨迹、链路可观测性的"白盒式"排错。围绕工具是否下发、是否被调用、参数是否正确等维度,剖析两者在定位精度、改造成本与适用场景上的核心差异,并给出可落地的四步排查法、对比表格与选型建议,帮助开发者少走弯路。
做智能体(Agent)应用时,真正消耗团队的往往不是”程序跑不起来”,而是”程序跑起来了却答错”。当一个查询请求返回错误或含糊的结论,你盯着最终那句话很难判断问题出在哪一层:是该查的数据没查?可能是程序压根没把工具交给模型,也可能是模型拿到了工具却迟迟不调用。这两种情况的修复位置完全不同——前者要改工具注册与路由,后者要改提示词与工具描述。正因如此,如何定位”出错的那一步”,成为智能体可维护性的关键。本文要对比的,正是两种应对这类问题的排查思路。
方案A:黑盒式排错(只看最终答案)
把智能体当成一个只暴露输入和输出的函数。出问题时盯着最终回复反复调提示词、换措辞、加”请仔细思考”之类的引导,试图直接”哄”出正确答案。它的隐含假设是:答案不对,就一定是提示词或模型的问题。
方案B:可观测性驱动的排错(基于执行轨迹与链路追踪)
把一次请求拆成一条可追溯的执行链:模型收到的上下文 → 是否下发工具 → 是否发起调用 → 参数校验 → 权限 → 调度执行 → 结果返回。出问题时沿着链路找到最早偏离预期的那一步,再针对性修复。它的隐含假设是:错误答案只是表象,根因藏在链路某个具体环节里。
两者并非对立,反而共享不少基础能力:
定位精度是最本质的区别。黑盒式只能看到”输入一句话、输出一句话”,无法区分”没查到”到底是工具没下发、没调用,还是调用失败。可观测式则把这三者拆开,一眼可辨。
信息完备度决定归因质量。可观测式保留了模型实际收到的上下文、工具清单、每次调用的参数与返回状态,因此能做”成功轨迹 vs 失败轨迹”的对照。例如成功的那条里模型发出了查询,失败的那条连工具清单里都没有这个工具,就能立刻定位到工具是在哪一步被筛掉的。
改造与投入节奏不同。黑盒式前期几乎零成本,改提示词即可;但链路一长、工具一多,反复试错的时间成本会急剧上升。可观测式前期需要埋点、接入采集,投入较高,但后期排查效率明显更高。
失败处理的严谨度也不同。可观测式更容易区分”查询成功但结果为空””查询超时””权限不足”等状态,从而给出诚实回复;黑盒式则容易把”超时”误表达成”确认无异常”。
| 维度 | 方案A 黑盒式排错 | 方案B 可观测性排错 |
|---|---|---|
| 定位精度 | 低,只能猜测问题层级 | 高,可锁定最早出错环节 |
| 信息来源 | 最终答案 + 少量日志 | 完整轨迹、工具清单、参数与返回 |
| 前期改造量 | 低 | 较高(需埋点与采集接入) |
| 后期维护成本 | 高(反复试错) | 低(对照轨迹即可定位) |
| 可复现性 | 差,依赖经验 | 强,可对比成功/失败轨迹 |
| 失败归因 | 未下发/未调用难区分 | 状态清晰可辨 |
| 适用阶段 | 原型快速验证 | 生产环境与复杂多工具链路 |
在只有一两个工具、链路很短的原型阶段,黑盒式足够用,快速调提示词验证想法即可。
当工具数量增多、涉及多步规划与工具编排时,可观测式的价值快速上升。此时”模型选了错误的工具””传了错误的服务名或时间窗””调用参数校验失败”等问题,只有沿链路才能查清。
对实时状态类、有硬性要求的任务(如告警查询、库存核对),建议直接采用可观测式,并由程序把”查询成功”设为输出结论的前提,避免模型在缺数据时凭空作答。
无论选哪种思路,都可套用以下四步,把排查系统化:
需要长期投入多工具智能体、且团队具备一定工程能力的场景,可优先考虑可观测性驱动的方式。业界常见的做法是接入某类开源 AgentOps 平台或某云厂商的日志服务、监控告警、链路追踪等通用能力,把执行轨迹采集下来再做诊断。像百度智能云这类平台提供的可观测性产品类别,可作为承载链路数据的候选之一,具体选型仍需结合团队技术栈与合规要求评估。
从黑盒式切换到可观测式时,需要提前评估几点:一是埋点侵入性,避免采集逻辑影响主链路性能;二是数据合规,上下文中可能含敏感信息,需做脱敏与权限隔离;三是存储与成本,轨迹数据量随调用量增长,要规划保留策略;四是兼容性,采集端若未上报工具清单或返回状态,应在调用边界补齐记录,否则会出现”轨迹存在但关键信息缺失”的盲区。
黑盒式排错胜在轻量、上手快,适合早期验证;可观测式排错胜在定位精准、可复现,适合生产环境下的复杂链路。两者的核心差异不在”谁更先进”,而在于你把成本花在了前面还是后面:黑盒式把成本留给反复试错,可观测式把成本前置到埋点与接入。对多数需要长期维护的智能体系统而言,建立执行轨迹、区分”没下发/没调用/调用失败”,是从”能跑”走向”可运维”的关键一步。