Agents' Last Exam轨迹(Trajectory)格式完全解析:ALE-v1.0统一轨迹规范API参考
Agents' Last Exam轨迹(Trajectory)格式完全解析:ALE-v1.0统一轨迹规范API参考
在 Agents' Last Exam(ALE)基准中,每一次 Agent 运行的完整过程都会被记录为一份统一轨迹(trajectory)。ALE-v1.0 轨迹规范把所有 Agent(Claude Code、Codex、OpenClaw、ALE-Claw 等)各自五花八门的日志,归一成同一套 JSON 结构——你读任何一份 trajectory.json,字段含义都完全一样。本文带你逐字段读懂这份规范。
🧭 为什么需要"统一轨迹格式"
ALE 的运行模式是:把任务描述交给 Agent,让它在真实沙箱里独立工作到完成,最后评分。问题是——每个 Agent 的记录格式都不同:claude-code 输出 stream-JSON 的 transcript.jsonl,openclaw 输出 event JSONL,还有各自的截图与工具调用埋点。
ALE 的解法很直接:每个 Agent 的 deployer 负责把自己"土著日志"翻译成 ALE-v1.0 的统一结构(见 agent_deployer.py 中的 parse_artifacts 契约),框架则保证所有运行都落成相同的文件集。这样:
- 回放、审计、跨 Agent 对比都不需要理解任何一家 Agent 的私有格式;
- 截图、Token 成本、耗时等元数据都进入同一 schema,可直接聚合统计。
规范的 Pydantic 模型定义在 trajectory.py,版本号常量固定为 "ALE-v1.0"(trajectory.py#L34)。
📦 Trajectory:顶层结构一览
Trajectory 表示一个完整的 episode(一次 Agent × 任务运行),核心字段如下:
| 字段 | 类型 | 必填 | 含义 |
|---|---|---|---|
schema_version |
"ALE-v1.0" |
✅ | 格式版本(常量) |
episode_id |
string | ✅ | 本 episode 的唯一 ID |
agent |
AgentInfo |
✅ | 是哪个 Agent 产出的轨迹(名称/版本/模型) |
task_path / variant_index |
string / int | ✅ | 运行上下文:任务与变体编号 |
instruction |
string | ⬜ | 交给 Agent 的提示词 |
steps |
Step[] |
⬜ | 有序的交互步骤(轨迹主体) |
final_metrics |
FinalMetrics |
⬜ | 全程汇总 + 结果(finalize 时写入) |
subagent_trajectories |
Trajectory[] |
⬜ | 子 Agent 的嵌套轨迹 |
continued_trajectory_ref |
string | null | ⬜ | 超长 episode 分片时,指向前一片文件 |
extra |
object | ⬜ | Agent 专属元数据的"逃生舱" |
💡 约定:所有对象拒绝未知字段,唯一的开放字典是三处显式的
extra字段;时间戳统一为 ISO-8601 UTC(如2026-06-05T03:11:48.520000Z)。
🔄 Step:轨迹的核心积木
Step 是轨迹中的一次"回合"(trajectory.py#L152-L177),其语义由 source 字段决定,共四种来源:
| source | 谁产生的 | 典型填充字段 |
|---|---|---|
user |
任务指令 / 人工回合 | message |
agent |
模型输出 | message、reasoning、tool_calls + metrics(Token/成本) |
environment |
环境响应(工具结果或状态更新) | observation |
system |
系统提示或框架事件(取消、超时等) | 说明性 message |
每个 Step 携带 step_id(从 1 递增)与 timestamp;message 可以是纯字符串,也可以是 ContentPart[](文本与图片混合的多模态内容)。
🔧 ToolCall → Observation → ToolResult:调用闭环
Agent 与环境的交互由三个模型构成严格的"请求—响应"闭环:
ToolCall(trajectory.py#L77-L84):Agent 在某 Step 发起的工具调用,含id(缺省自动生成call_…)、name、arguments。Observation:环境对上一步若干工具调用的回应,results按tool_call_id与前置调用对齐;若只是纯状态更新,results可为空。ToolResult:单个工具的结构化结果,content为ContentPart[](文本或图片),is_error标记是否失败。
这个"调用在 agent Step、结果在下一个 environment Step"的错位设计,与主流 LLM 对话日志的语义完全一致,方便直接映射。
🖼️ 多模态内容:图片永远按路径引用
ContentPart 是"一块结构化内容":type 为 "text" 时填 text,为 "image" 时填 image(一个 ImageSource)。
ImageSource 支持三种引用方式,但持久化后只允许路径形式:
| type | 说明 |
|---|---|
path |
✅ 首选,相对运行目录的路径(如 screenshots/0000.png) |
base64 |
deployer 可临时内联提交,落盘前会被框架搬走 |
url |
远程地址 |
框架承诺:内联 base64 截图永远不会存活到持久化的 trajectory.json 里。persist_screenshots()(trajectory.py#L404-L482)在序列化前把所有 base64 截图写入 <run_dir>/screenshots/NNNN.<ext>,并把引用改写为相对路径——单张截图解析失败只会记录警告并跳过,不会中断整条轨迹的落盘。
📊 指标体系:StepMetrics 与 FinalMetrics
StepMetrics:单步 LLM 账单——input_tokens、output_tokens、cache_read_tokens、cache_creation_tokens、cost_usd、duration_ms,全部可选,"有什么填什么"。FinalMetrics:轨迹级汇总。Token/成本/时长默认由逐步StepMetrics累加得出;而reward(grader 评分)与status(completed/timeout/failed)不参与逐步累加,由评分器与 runner 在结束时填入。
若 Agent 的日志能算出更精确的全局总数(例如 prompt 缓存读写拆分),deployer 可通过 TrajectoryBuilder.override_final_metrics() 记录权威值,finalize() 时优先采用(trajectory.py#L273-L290)。
🌿 子 Agent 与超长轨迹分片
subagent_trajectories:Agent 派生的子 Agent(如 claude-code 的 Task 工具、原生子循环)的完整轨迹,以嵌套Trajectory挂载,递归遍历。continued_trajectory_ref:episode 过长时,写入器每 N 步刷盘并开新分片,新分片用该字段指向前一片的相对路径。拼接规则:沿引用链回溯到null,再按序拼接所有 steps。
🗂️ 一次运行如何落盘
运行结束后,run_writer.py 的 write_trajectory() 通过 trajectory.model_dump_json(indent=2) 写入运行目录,目录布局固定:
.logs/<experiment>/<run_id>/<agent>/<model>/<task>/v<variant>/<timestamp>/
├── events.jsonl 追加式阶段日志(权威过程记录)
├── run.json 元数据、最终分数、终止原因、用量汇总
├── trajectory.json ALE-v1.0 统一轨迹
├── screenshots/ Agent 看到的截图(被轨迹按路径引用)
├── eval_result.json 评分器裁决(status/score/耗时)
├── origin_log/ Agent 的原始工作目录(从沙箱原样拉取)
└── output/ Agent 产出的文件(若环境配置了收集)
翻译责任在 deployer 侧:例如 claude-code 的 deployer 逐行读取 stream-JSON 转录,assistant 事件变成 agent Step(携带工具调用),工具结果变成 environment observation,逐条 usage 累加并与运行总账核对(claude_code/deployer.py);ALE-Claw 的转录翻译逻辑则单独放在 transcript_to_trajectory.py。输入日志残缺也是合法的:deployer 只需发一条 source="system" 的 Step 说明缺口即可。
🧩 快速上手:核心代码地图
| 你想做什么 | 看哪里 |
|---|---|
| 读/生成轨迹 | ale_run/base_interface/trajectory.py(模型 + TrajectoryBuilder) |
| 实现新 Agent 的日志翻译 | ale_run/base_interface/agent_deployer.py 的 parse_artifacts 契约 |
| 运行目录写入逻辑 | ale_run/orchestration/run_writer.py |
| 字段级 API 参考文档 | docs/ale-docs-site/pages/trajectory-schema.html |
| 轨迹与产物总览 | docs/ale-docs-site/pages/trajectories.html |
TrajectoryBuilder(trajectory.py#L235-L343)是推荐的构造路径:add_step() 追加步骤并自动编号,finalize(reward=…, status=…) 一次性结算指标并封口——框架在生命周期中先 seed 一条 user 来源的指令 Step,再由 deployer 补齐其余部分。
写在最后
ALE-v1.0 的设计哲学可以概括为三句话:严格子集(只保留通用需要的字段,Agent 专属信息走 extra)、路径优先(截图永不内联)、增量构建、一次封口(builder 逐步追加,finalize 只执行一次)。理解了这套规范,你就能不看任何 Agent 的私有文档,直接读懂并对比 ALE 上所有运行轨迹了。
