Agent 执行轨迹怎么排错？复盘一次运行的可见证据

Agent 的最终回答写错了数量，或者人工已经改过审批，实际工具却用了旧参数。只看最后一句和一条工具错误日志，很容易把问题归到模型。单次运行轨迹复盘要回答的是：这一项任务中，可观察的行为在哪一个交接点首次偏离验收要求？证据够不够支持这个判断？

本页从一次已发生的运行出发。Agent 循环护栏决定运行时下一步能否继续；工具调用契约规定接口和执行端的责任；恢复手册处理已发生外部效果后的接管与补偿；漂移监控比较多次运行的趋势。这里制作的是交给这些环节使用的逐事件证据记录。若问题只是回答内容质量，也可先用回答失败诊断树分类；本页进一步核对每次调用实际发生了什么。

先锁定一次运行和验收差异

写下请求者真正要完成的任务、合格条件、用户看到的结果，以及需要核查的外部状态。例如“列出所有待处理报价”，合格条件必须包括分页结束；“按人工修改后的值派单”，合格条件必须包括工具实际使用的参数。没有明确差异，就无法判断哪条事件重要。

用这次运行的 trace ID 或应用请求编号定位材料，同时记录开始时间、时区、工作流版本、模型与 Prompt 版本、工具结构版本，以及审批规则。一个会话可能包含多次运行；不要只凭会话编号把前一次的工具返回接到这一次。若使用 OpenAI Agents SDK，trace 可以包含多种 span；其 group_id 可把同一会话中的不同 trace 关联起来，但不能代替单次运行编号。其他框架的命名可能不同。

按父子关系重建事件，而不是按日志窗口猜顺序

OpenTelemetry 把一次操作的路径表示为 trace，把有起止时间的工作单元表示为 span；trace ID 和 parent span ID 帮助还原跨组件的层级。把根请求、模型调用、工具执行、子 Agent 交接、人工审批与最终展示排进一条表，并保留各自的编号和时间。并行步骤可能在时间上交错，不能把屏幕上相邻的两行认作因果关系。工具调用编号可连接模型提出的调用与执行端记录；外部操作编号则用于向目标系统查询真实效果。

每一行至少区分五件事：模型可见地提出了什么动作；执行端经过验证与权限检查后实际发送了什么；工具返回了什么，包括分页游标、错误码和“结果未知”；下一轮模型实际收到了哪份观察；用户或人工审核者最后看到了什么。一次 HTTP 200 只表示请求成功返回，不说明任务完成，更不说明模型看到了全部资料。审批人修改了参数，也不说明执行端一定采用了修改后的版本。

OpenTelemetry 的 GenAI 语义约定给出 execute_tool、工具调用编号等可参考字段，但该 GenAI 约定仍标为 Development；本文的复核方法不依赖某个属性名永远不变。OpenAI Agents SDK 的追踪文档列出 generation、function、handoff 和 guardrail 等 span。接入时以正在使用的 SDK 版本和实际导出结构为准，必要时为业务审批与最终展示补自定义事件。

找第一个有证据的偏离点

从合格条件倒着问，再沿事件链从头核对。若最后答复遗漏一项，先看工具是否提供了那项；若工具已提供，再看模型输入或下一动作是否忽略了它；若模型提出了正确动作，检查后端是否改变了参数或拒绝执行。只把观察到了的事实写成事实。例如“模型输出了一次 list_quotes 调用”是可核查事件，“模型心里认为只有一页”不是。

用三种结论避免过度断言：已证实指有相互关联的事件和权威状态；待核查指轨迹提供了线索，但需要工具服务或人工记录确认；无法复原指采样、导出延迟、跨度缺失或记录损坏让关键步骤不可见。缺少工具 span 不能证明工具没有执行。OpenAI Agents SDK 默认批量异步导出，运行刚结束时看板可能尚未出现全部 span；应先检查导出状态，再补应用与目标系统记录。必要时补埋点，而不是从空白推断“没有发生”。

案例一：报价清单把第一页当成全部

采购助理 Agent 被要求列出本周所有仍待处理的供应商报价。工具 list_quotes 第一页返回 8 条记录和一个非空 next_cursor。Agent 随后直接回答“共 8 条”，没有发出带游标的下一次调用。复核者通过同一查询条件查看第二页，确认还有 3 条。

这次轨迹里，工具第一步并未报错，第一处偏离发生在返回游标已出现，却宣称清单完整的交接。可填写的事件行分别记录原请求筛选条件、第一页返回数量与游标状态、下一次模型可见输入、缺失的续页调用和最终断言。修复不是提高模型温度或更换模型，而是让完成条件要求“游标为空或明确达到授权上限”，并在评测中加入至少两页的样例。若后端根本没有导出游标，结论就只能是“待核查”，先修记录链路。

案例二：人工改判没有进入实际派单

设备故障分流 Agent 提议把一张工单交给东区值班组。审核人查看现场位置后，把批准目标改成西区值班组。审批记录显示西区版本已批准；执行端的 assign_ticket 调用却仍使用东区参数。Agent 最终向请求者报告“已交给西区”。工单系统中的当前负责人是东区。

把提议参数、批准后的参数与实际发送参数各做一个脱敏摘要或指纹，按审批版本、工具调用编号和工单操作编号对齐。首个可证实偏离是审批修改已记录，但执行请求未绑定该修改；后面的错误告知是第二道防线也失效。先向工单系统确认真实负责人，并按恢复手册决定是否更正与通知；不能仅凭 Agent 的“成功”文字再派一次。回归测试要覆盖审核人修改、拒绝、审批过期和执行前参数变化，而不是只测“直接批准”。

留下能复核、又不会泄漏的记录

一张实用复核表分成总记录和可复制的事件行。总记录填任务、验收差异、运行编号、版本、观察范围和复核者；每行填 span 与父节点、发生时间、可见动作、工具调用编号、提议与实际参数摘要、校验/审批结果、返回状态、模型收到的观察、外部状态及证据位置。最后写首个偏离点、可能的替代解释、缺失埋点、最小复测、负责人和关闭条件。另一位复核者应能从这些字段重建结论，不必猜测截图的上下文。

轨迹内容要按数据边界采集。OpenTelemetry 将模型输入、输出及工具参数、结果列为可选择记录的内容，并提示可能包含敏感信息；OpenAI Agents SDK 文档说明 generation 和 function span 可含输入/输出，且 trace_include_sensitive_data 默认开启。上线前核对实际设置、导出目的地、访问权与保留期。优先保存脱敏编号、版本、结构化状态和受控证据指针，不把整段用户提问、凭据、隐藏的内部推理或机密工具结果贴进本站工作台；此工具会在当前浏览器自动保存草稿。若必须查原文，应到获授权的原系统核验。对于要求零数据保留的 OpenAI API 组织，该 SDK 文档明确说明其追踪不可用，须用符合本地要求的其他观测方案。

复核后只改一个可检验的环节

把原运行输入、配置和可用的工具响应保存为获准的测试快照。针对首个偏离点提出一个能失败的假设：补上分页完成检查是否阻止漏项？让审批版参数成为执行端唯一来源，是否消除旧值？用合成数据重放，只改变这个环节，检查原失败和邻近正常案例。涉及写入的运行先查权威外部状态；不能为了排错直接重放生产写入。

若诊断仍停在缺失事件，就先补齐关联编号与边界事件，再谈修复模型行为。把人工改判的原因、首次偏离和最终关闭证据分别留下，下一次类似问题才能被快速定位；跨运行出现同类失败时，再把它送入漂移观察板看范围和变化。

不适用边界

轨迹记录显示可观察的输入、输出与动作，不能展示模型未公开的内部推理，也不能凭一个成功状态证明业务结果正确。采样、异步导出和跨系统关联缺口会限制结论；外部写入是否生效以目标系统为准。逐次复盘也不能替代权限控制、线上告警、统计评测或事故恢复。高风险事件应按现有响应流程处置，复盘表只为它提供可靠证据。