主题
第 19 章 · Agent 轨迹数据
核心观点 + 逻辑框架（调优篇 · 轨迹：看懂真实执行，把记录留成样本交给 Pipeline）
▍速览
一句话版（开场，约 20 秒）
轨迹把输入、行动、工具反馈与输出放在一起，让业务人员沿着实际过程找到改进方向。分析路径是：先找一条自己知道发生了什么的任务核对采集，按问题选检索方式缩小范围，读轨迹先看目标与结果再展开关键步骤，把工具失败、耗时偏高、业务质检三类问题落到具体行动，最后把有价值的记录留成候选样本、把规则交给 Pipeline 重复应用。
一段话版（完整表达，约 90 秒）
用户反馈没解决问题时，要区分 Agent 是没理解需求、没找到材料还是没用对材料——轨迹把输入、行动、工具反馈与输出放一起，让改进落到具体环节。先找一条自己执行过的任务核对采集：问题、回答、工具调用与返回都要可见；列表为空依次查 AgentSpace、时间、筛选与采集，区分"没采到"和"没做对"。检索按问题选：TraceID 精确查某次执行，SessionID 看连续交互，无标识用应用+模型+工具+时间组合；关键字匹配原话、语义搜同义表述，相似度只选候选、不等于质量分。读轨迹先看输入输出定目标与结果，再看概览沿用户补充、行动、工具返回展开。三类问题各有落点：工具失败先看 Agent 怎样处理错误、误报成功要改回复策略；耗时偏高先找多出来的工作、不因总 Token 高就删步骤；业务质检看回答与执行事实是否一致，材料不足先记待确认。有价值的记录留成候选样本，业务确认入黄金集，规则交 Pipeline 重复应用。三个对象：Trace 是一组关联调用，Session 是可能含多条 Trace 的连续交互，Trajectory 是整理后的行为主干；SessionID 不自动证明属同一任务。
- 起点 先找一条自己知道发生了什么的任务，核对采集真实性
- 检索 TraceID 精确 / SessionID 连续 / 组合筛选；相似度≠质量分
- 读法 目标与结果 → 概览 → 执行步骤；多 Agent 看委派与实收
- 行动 工具失败 / 耗时偏高 / 业务质检三类问题各自落点
- 沉淀 候选样本→黄金集；规则交给 Pipeline 批量重复
收尾
结论要落到一组相邻事实——"要求操作步骤 → 检索返回了步骤 → 回答遗漏步骤"，单独写"回答质量不好"，下游不知道该检查什么。
▍逻辑框架（记忆卡片）
① 命题：轨迹让改进落到具体环节
- 用户反馈没解决时，需要区分：没理解需求 / 没找到材料 / 没用对材料——三者改进方向不同
- 轨迹把输入、行动、工具反馈与输出放在一起，业务人员沿实际过程找改进方向，不靠猜测
- 分析顺序：找到已知任务 → 检索缩小范围 → 读轨迹 → 三类问题落行动 → 留样本交 Pipeline
轨迹记录一次执行发生了什么；重新实验还需要题目、运行入口、必要环境与评分标准——轨迹是飞轮的原料入口，不是结论本身。
② 找一条自己知道发生了什么的任务
- 用自己的提问跑一条任务，记录执行时间、问题与回答，保留 TraceID/SessionID，核对记录是否正确
- 列表为空时依次检查：AgentSpace → 时间范围 → 筛选条件 → 采集状态，再回观测页确认新请求有没有上报；首次接入先确认轨迹清洗与采集已开启，阅读界面的处理与费用提示后再开启
- 区分数据未采集与 Agent 未正确执行：配置完发一条新任务验证，不要仅凭开关已开就认为数据到达，也不要用发业务请求代替定位
- 第一条看对后再挑一个失败任务（查错误反馈是否保留）和一个多轮任务（查用户补充信息能否找到）
此时才拥有了可日常使用的分析入口。
③ 按问题选检索方式，逐步缩小范围
- TraceID：已知具体执行，精确查找；SessionID：查看一段连续交互；无标识用 Agent 应用+模型+工具名+时间范围组合
- 筛选从少到多增加，结果为空先撤掉最近加的条件；输入框查用户需求、输出框查 Agent 回答，按调查目标选择
- 关键字匹配：已知原话、产品名、错误表述；语义搜索：找意思相近措辞不同的问题（"怎么给回答评分/怎样建评测任务"）
- 相似度只负责选出候选，不代表同难度或同错误；不要把搜索分数当作质量分
找到一组记录先读几条代表样本：概念型与操作型分开分析——混在一起会把简短但合适的回答判为不完整，或把泛泛介绍误认为解决了操作问题。
④ 读一条轨迹的顺序
- 1 先看输入输出：用户最终要求是什么、Agent 给了什么答案
- 2 看概览：步骤数、工具调用、Tokens、耗时，确定重点检查环节，不逐字读全部
- 3 沿执行步骤阅读：用户补充 → Agent 行动 → 工具返回 → 后续回答；"搜索步骤"定位工具名/关键内容/错误提示
- 4 工具调用展开入参与执行结果，查看调用身份、耗时与 Token；需核对字段、调用标识或导出结构时用"查看轨迹 JSON"，记录缺失或对应关系存疑再交工程人员按身份回查采集记录，业务结果仍以工具反馈与业务状态为准
- 多 Agent：看主 Agent 交给子 Agent 的目标与实际收到的返回，不能只看子 Agent 是否结束；并行显示的步骤未必有先后依赖，结合调用关系理解
例：用户问"如何做评估"——检查检索词是否针对评估流程、返回是否含操作说明、回答是否使用了内容；检索有完整步骤而输出只给概念与"知识库根本没有材料"是两个不同的改进方向。
⑤ 三类问题落到具体行动
- 工具失败：先判断 Agent 怎样处理失败——是否追问原因、修改参数、重新调用；收到"缺少退款原因"却回复"申请已提交"→ 改错误处理与回复策略；返回没清楚表达失败 → 同时检查工具接口；业务是否真产生退款申请还要核对业务系统结果
- 重试过程：修正参数后成功=能恢复；多次原样重试同一错误=调整重试或停止条件——都出现失败调用，但不是同一个调优建议
- 耗时/Tokens 偏高：找多出来的工作——反复检索同一材料（新信息有价值、结果没变化可复用）、工具返回大量无关内容、多次尝试同一动作；不因总 Tokens 高就删步骤（复杂任务需要探索，必要测试也增加消耗），质量、耗时与消耗一起比
- 业务质检：回答与执行事实是否一致；"完成"是输出，工具接收请求、任务执行结束、业务目标达成不是同一件事；材料不足先记录待确认，别把采集问题直接变成 Badcase
分析后明确下一步：补知识、修工具、改回答策略、调整执行流程或先补数据，再经评估与实验验证修改。
⑥ 把有价值的记录留成样本，规则交给 Pipeline
- 详情页"加入数据集"或列表勾选多条；首次建候选集保留用户输入、Agent 输出与轨迹内容，需分析来源再加应用/模型/工具/Tokens 字段
- 写入已有 Dataset 核对字段映射，不要把最终答案和完整轨迹接反；写入后打开检查题目、回答与必要过程是否在同一条记录
- 候选样本 → 业务人员确认问题成立、补充期望行为 → 进黄金集；失败例与正常例都要保留，避免只改善投诉样本却损害常规回答
- 批量处理走 Pipeline（后台任务）：确认时间范围、筛选条件与目标数据集后检查实际入库；"任务已创建"≠数据已写入
单条复盘发现规则，Pipeline 把规则重复应用到更多数据（如操作类轨迹=用户问题+检索结果+最终回答+工具状态，重复投递去重，按场景分流）；业务目标与样本一起交给管线，逐步形成可复用处理流程。
⑦ 三个对象：Trace / Session / Trajectory
左：Trace 追踪上下文关联的一组调用（模型/工具/服务操作）；适合定位某次执行与调用问题；可见范围取决于实际采集
右：Session 应用关联的一段连续交互，可能含多条 Trace；适合查看用户补充与上下文；同一会话中可能有多个任务
Trajectory：整理后的用户与 Agent 步骤、工具交换、结果与指标；适合阅读行为、分析加工样本；仍需核对覆盖哪些任务部分
一次同步问答可能恰对应一条 Trace；多轮、异步回调或子 Agent 可能留下多份记录。SessionID 帮助查找相关交互，但不自动证明属于同一任务——需要应用提供可靠的身份与关联，不凭时间接近或文字相似认定已恢复完整任务。轨迹整理提取行为主干、减少模型请求中反复携带的历史、关联工具请求与返回；重试有分析价值，失败/缺失返回/未取得业务结果分别对待；ATIF 是可交换轨迹的统一结构。
ATIF：步骤·消息·工具调用与观察·运行指标·来源扩展 · 统一结构让展示、Pipeline、评估复用同一份行为材料
▍逻辑全景图（轨迹分析流：找任务 → 检索 → 读轨迹 → 三类诊断 → 沉淀样本）
从"知道发生了什么"到"结论落到相邻事实"，再到样本与规则进入飞轮
- 定位与读取
- 三类问题诊断
- 沉淀：样本 + Pipeline
示意 · 按第 19 章正文重构：检索读法、三类诊断与样本沉淀路径
▍书中关键图（SVG 重绘版·示意）① 三个对象：Trace / Session / Trajectory 的关系
示意 · 按原书表 19.6 与正文重构
▍书中关键图（SVG 重绘版·示意）② 按问题选择检索方式
三种定位方式 + 五类调查问题的找法对照；输入/输出检索分关键字与语义两种模式
| 想调查的问题 | 在列表中怎样开始找 | 具体操作 |
|---|---|---|
| 某次用户投诉 | TraceID · 精确查某次执行（已知具体执行、投诉定位时优先使用） | 时间范围配合 TraceID，或用户输入中的关键字 |
| 多次补充信息仍未解决 | SessionID · 查一段连续交互（用户多次补充信息、上下文相关时使用） | SessionID，结合相关输入和输出 |
| 某个工具的任务表现不佳 | 组合条件 · 无标识时定位（Agent 应用 + 模型 + 工具名 + 时间范围） | Agent 应用、工具名和对应时间范围 |
| 哪些任务明显变慢 | 组合条件 · 按耗时范围筛选 | 同一应用按耗时范围筛选，再比较 Steps 和 Tokens |
| 同一业务意图反复出现 | 语义搜索 · 意思相近措辞不同 | 对输入使用语义搜索，打开结果确认是否属于目标场景 |
| 总则 | 先按问题选定位方式，再逐步缩小范围 | 条件从少到多，为空先撤最近加的 |
示意 · 按原书第 19.2 节检索方式表重绘；关键字匹配适合已知原话、产品名或错误表述，语义搜索适合意思相近措辞不同的意图；相似度只选出候选，不等于相同难度或相同错误