Trajectory schema (ALE-v1.0)

The canonical record ALE emits for every run. Each agent's deployer translates its native logs into this shape, so every run reads the same way regardless of the harness underneath. This page is the field-by-field specification.

Conventions

schema_version is the constant string "ALE-v1.0".
Timestamps are ISO-8601 UTC with microseconds, e.g. 2026-06-05T03:11:48.520000Z.
Objects reject unknown keys. The only open maps are the explicit extra fields on Trajectory, Step, and AgentInfo: the escape hatch for agent-specific metadata.
Images are referenced by relative path under the run directory; the framework moves any captured image to screenshots/ before the trajectory is written (see ImageSource).
"Req" below: yes = no default, must be present; no = defaulted/optional. Types use | for unions and [] for arrays.

Trajectory

Trajectory is the top-level object: one complete episode.

Field	Type	Req	Meaning
`schema_version`	`"ALE-v1.0"`	yes	Format version (constant).
`episode_id`	`string`	yes	Unique id for this episode.
`agent`	`AgentInfo`	yes	Which agent produced the trajectory.
`task_path`	`string`	yes	The task this run is for (run context).
`variant_index`	`integer`	yes	Which task variant (run context).
`instruction`	`string`	no	The prompt handed to the agent. Default `""`.
`steps`	`Step[]`	no	The ordered interaction. Default `[]`.
`final_metrics`	`FinalMetrics` \| null	no	Trajectory-wide totals and outcome (set at finalize).
`started_at`	`string`	no	When the episode began (ISO-8601).
`ended_at`	`string` \| null	no	When it ended.
`subagent_trajectories`	`Trajectory[]`	no	Full nested traces of any sub-agents the agent spawned. Default `[]`.
`continued_trajectory_ref`	`string` \| null	no	When an episode is split across files, the relative path of the previous chunk. Walk the chain back until `null`, then concatenate steps.
`extra`	`object`	no	Agent-specific metadata that doesn't fit the standard shape. Default `{}`.

AgentInfo

Field	Type	Req	Meaning
`name`	`string`	yes	Agent identifier, e.g. `"claude-code"`, `"ale-claw"`.
`version`	`string` \| null	no	CLI version or commit.
`model`	`string` \| null	no	The LLM id the agent used.
`extra`	`object`	no	Agent-specific metadata.

Step

One turn in the interaction. Its shape varies by source.

Field	Type	Req	Meaning
`step_id`	`integer` (≥ 1)	yes	Ordinal position, starting at 1.
`timestamp`	`string`	no	When the step occurred (ISO-8601).
`source`	`"system" \| "user" \| "agent" \| "environment"`	yes	Who produced the step (see below).
`message`	`string` \| `ContentPart[]` \| null	no	Text, or multimodal content.
`reasoning`	`string` \| null	no	The agent's reasoning trace, when exposed.
`tool_calls`	`ToolCall[]`	no	Tools the agent invoked this step. Default `[]`.
`observation`	`Observation` \| null	no	The environment's response.
`metrics`	`StepMetrics` \| null	no	LLM accounting for this step.
`extra`	`object`	no	Step-specific metadata (e.g. `screenshot_index`, `screenshot_path`). Default `{}`.

The four source values carry different fields:

user: an instruction or human turn; message is set.
agent: model output; some combination of message, reasoning, and tool_calls, with metrics recording the call's tokens and cost.
environment: the environment's reply; observation is set (tool results or a state update).
system: a system prompt or framework note (cancellation, timeout, …).

ToolCall

A single tool invocation emitted by the agent within a step.

Field	Type	Req	Meaning
`id`	`string`	no	Unique call id; a later `ToolResult` references it. Auto-generated (`call_…`) if absent.
`name`	`string`	yes	Tool name.
`arguments`	`object`	no	Arguments passed. Default `{}`.

Observation

The environment's response to one or more tool calls. results align with the tool_calls of the previous step, matched by id. A pure state update (no preceding call) may leave results empty and carry content on the step's message.

Field	Type	Req	Meaning
`results`	`ToolResult[]`	no	One result per preceding tool call. Default `[]`.
`error`	`string` \| null	no	An environment-level error, if any.

ToolResult

Field	Type	Req	Meaning
`tool_call_id`	`string`	yes	The `ToolCall.id` this answers.
`content`	`ContentPart[]`	no	The result: text and/or image. Default `[]`.
`is_error`	`boolean`	no	Whether the tool failed. Default `false`.

ContentPart

One piece of structured content: either text or an image.

Field	Type	Req	Meaning
`type`	`"text" \| "image"`	yes	Which kind of content.
`text`	`string` \| null	cond.	Set when `type = "text"`.
`image`	`ImageSource` \| null	cond.	Set when `type = "image"`.

ImageSource

A reference to an image. path is preferred. Inline base64 (data) is accepted from deployers but discouraged for long episodes. The framework moves captured base64 to screenshots/NNNN.png and rewrites the reference to type = "path" before the trajectory is persisted.

Field	Type	Req	Meaning
`type`	`"path" \| "url" \| "base64"`	no	How the image is referenced. Default `"path"`.
`path`	`string` \| null	cond.	Relative path under the run dir.
`url`	`string` \| null	cond.	Remote URL.
`data`	`string` \| null	cond.	Inline base64 (transient, moved to disk).
`media_type`	`string`	no	MIME type. Default `"image/png"`.
`alt_text`	`string` \| null	no	Optional description.

StepMetrics

Per-step LLM accounting. Every field is optional: populate what the agent reports.

Field	Type	Req	Meaning
`input_tokens`	`integer` \| null	no	Prompt tokens.
`output_tokens`	`integer` \| null	no	Generated tokens.
`cache_read_tokens`	`integer` \| null	no	Prompt tokens served from cache.
`cache_creation_tokens`	`integer` \| null	no	Tokens written to cache.
`cost_usd`	`float` \| null	no	This step's API cost.
`duration_ms`	`integer` \| null	no	Wall-clock for this step.

FinalMetrics

Trajectory-wide totals plus the outcome. The token, cost, and duration totals are summed from per-step StepMetrics; reward and status are not rolled up from steps. They are filled in by the grader and the runner at the end.

Field	Type	Req	Meaning
`total_steps`	`integer`	no	Number of steps. Default `0`.
`total_input_tokens`	`integer`	no	Sum of step input tokens.
`total_output_tokens`	`integer`	no	Sum of step output tokens.
`total_cache_read_tokens`	`integer`	no	Sum of cache reads.
`total_cache_creation_tokens`	`integer`	no	Sum of cache writes.
`total_cost_usd`	`float`	no	Sum of step costs. Default `0.0`.
`total_duration_ms`	`integer`	no	Total wall-clock.
`reward`	`float` \| null	no	The grader's score, set at evaluation. Not a step metric.
`status`	`"completed" \| "timeout" \| "failed"`	no	How the run ended. Default `"completed"`.

Where this lives

The Pydantic models are in ale_run/base_interface/trajectory.py; deployers populate them via TrajectoryBuilder. How a run's files fit together is covered in Trajectories & artifacts.