Agents' Last Exam轨迹(Trajectory)格式完全解析:ALE-v1.0统一轨迹规范API参考

原创2026-10-15 18:43:031,458 阅读

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,字段含义都完全一样。本文带你逐字段读懂这份规范。

Agents' Last Exam统一轨迹评测基准覆盖13个行业簇与55个子领域任务

🧭 为什么需要"统一轨迹格式"

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 与环境的交互由三个模型构成严格的"请求—响应"闭环:

  1. ToolCall(trajectory.py#L77-L84):Agent 在某 Step 发起的工具调用,含 id(缺省自动生成 call_…)、name、arguments。
  2. Observation:环境对上一步若干工具调用的回应,results 按 tool_call_id 与前置调用对齐;若只是纯状态更新,results 可为空。
  3. 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 上所有运行轨迹了。

登录后查看全文
agents-last-exam