By name: agent-trajectory-analysis description: Analyze Agent experiment trajectories from JSON/JSONL session logs. When given a case file or directory, record experiment background, Agent behavior, step-by-step trajectory, compare against expected results with verifiable evidence locations, identify problems, and suggest improvements. disable-model-invocation: true
Agent 实验轨迹分析
概述
当用户提供 Agent 实验的会话日志（JSON 文件）时，对其进行系统性的轨迹分析。 目标是：把 Agent 的完整行为拆成可追溯、可验证的阶段报告，防止幻觉—— 每个关键结论都必须能定位到具体轮次和原始消息。
何时使用
- 用户给了一个
messages.json文件或一个包含多个 case 的结果目录 - 用户说"帮我分析这个 case" / "看看这个 Agent 跑得怎么样"
- 用户想对比多个 case 的 Agent 表现
不要用于：代码 review、性能调优分析、架构讨论。
分析流程
0. 记录实验背景
拿到 case 后，先建立上下文。这部分是后续分析的锚点：
| 字段 | 说明 | 来源 |
|---|---|---|
| 实验背景/版本 | 这是什么实验？来自哪个分支/提交/时间？ | 目录名、git log、文件名 |
| 结果目录 | 完整的输出路径 | 文件路径 |
| 启动脚本 | 如果有的话，Agent 是怎么启动的 | 目录中的 .sh / .py 脚本 |
| Case 名称/描述 | 这个 case 是什么内容 | 目录名、messages.json 第一条 user 消息 |
| Case 来源 | 来自哪个 benchmark / 项目 / 手工编写 | 目录层级结构推断 |
| 期待结果 | 理想情况下 Agent 应该产出什么 | user prompt、skill 文档、benchmark 要求 |
1. 提取关键指标
遍历 messages.json，统计以下指标：
| 指标 | 提取方式 |
|---|---|
| 耗时 | 从时间戳或外部记录 |
| 对话轮次 | 消息总数 - 1（去掉第一条 user） |
| Tool calls 总数 | 统计所有 assistant 消息中 tool_calls 的数量 |
| Input tokens | 如果有 token 统计字段 |
| Output tokens | 如果有 token 统计字段 |
| 使用的工具类型 | 统计每个工具被调用了多少次 |
| 工具失败次数 | 工具返回中 status 非 success 或报错的 |
2. Agent 行为轨迹分析（核心）
对每一轮对话按阶段分组，分段总结而不是逐条罗列。
2a. 阶段划分原则
不要把 50 轮对话一条条讲。按 Agent 在解决什么问题来分段：
阶段 1: [轮次 N-M] 在解决什么问题
- 调了哪些工具，各做了什么
- 关键节点是什么
阶段 2: [轮次 N-M] 在解决什么问题
- ...
阶段划分线索：
- Agent 显式说"现在我要做 X" → 新阶段
- 工具类型发生明显切换 → 可能新阶段
- 出现错误重试循环 → 记录为子阶段
2b. 每轮记录格式
在阶段内部，简要记录每一步：
[第 X 轮] agent: <意图摘要，不超过一句话>
└ 调用: tool_name(args摘要)
└ 返回: <结果摘要，不超过30字>
└ 状态: ✅ / ❌ / ⚠️
2c. 关键节点标记
标记以下事件为关键节点：
- 第一次成功调用核心工具
- 工具调用失败及其修复方式
- Agent 改变策略的时刻
- 产生最终结果的那一步
- Agent 表现出明显困惑或重复操作的区域
3. Case 结论
和预期结果对比，回答以下问题：
- Agent 最终产出 vs 期待：完成了什么，差了什么
- 关键结果溯源：如果产出了关键结果，指出是在哪一轮、哪个工具返回中产生的
- 完整性评估：✅ 完整 / ⚠️ 部分 / ❌ 未完成
- 是否出现幻觉：Agent 有没有把"期待的结果"当成"真实结果"来说
防止幻觉的检查清单
- Agent 是否引用了实际 tool 返回中的数据？还是在说"我认为应该是 X"？
- 对比
assistant.content和对应tool.return_content：两者一致吗？ - Agent 有没有跳过失败的工具调用，直接宣布成功？
- 最终结论中的数字/结果，能在 tool 返回中找到对应吗？
4. 问题与改进方向
总结这个 case 暴露的问题：
- 结构性问题：Agent 是否走入了不必要的探索循环？
- 工具使用问题：是否反复调用同一个工具失败？
- 上下文问题：Agent 是否丢失了对初始目标的追踪？
- 效率问题：哪些步骤可以合并或跳过？
- 改进方向：具体的 skill 更新、prompt 调整、或工具增强建议
输出格式
分析报告按以下结构输出：
## 实验背景
| 字段 | 内容 |
|---|---|
| 实验背景/版本 | ... |
| 结果目录 | ... |
| 启动脚本 | ... |
| Case | ... |
| 来源 | ... |
| 期待结果 | ... |
## 关键指标
| 指标 | 值 |
|---|---|
| 耗时 | ... |
| 对话轮次 | ... |
| Tool calls | ... |
| Input tokens | ... |
| Output tokens | ... |
| 流程解析 | ✅/⚠️/❌ |
| 基准提取 | ✅/⚠️/❌ |
| 优化脚本 | ✅/⚠️/❌ |
| 优化结果 | ✅/⚠️/❌ |
## Agent 行为轨迹
### 阶段 1: [一句话描述这个阶段在做什么]
[第 N 轮] agent: ...
└ ...
### 阶段 2: ...
### 关键节点总结
1. ...
2. ...
## Case 结论
### 与预期对比
...
### 关键结果溯源
...
### 完整性
...
### 幻觉检查
...
## 问题与改进方向
1. ...
多 Case 对比
如果用户给了一个包含多个 case 的目录：
- 先对每个 case 单独跑上面的分析
- 最后加一个横向对比表
常见陷阱
- 不要把 Agent 的 reasoning 当成事实 — reasoning_content 是 Agent 的想法，tool 返回才是结果
- 不要跳过失败的 tool 调用 — 这些往往是分析的重点
- 不要逐条罗列 50 轮对话 — 按阶段分组，保留关键节点
- 关键结论必须能溯源 — 给出具体轮次编号
- 不要忽略 token 消耗分布 — 哪一轮消耗最多，往往说明 Agent 在那里卡住了