The Hierarchy
A single agent conversation maps to this four-level hierarchy:| Level | What it is | Count |
|---|---|---|
| Trajectory | The entire conversation, start to finish | One per conversation |
| Step | A snapshot of the conversation at one decision point, containing all messages up to that point (cumulative) | One per turn |
| Turn | One user → agent exchange (user speaks, agent thinks/acts/responds) | One or more per trajectory |
| Message | A single message: user input, assistant output, tool call, or tool result | One or more per turn |
Trajectory
A Trajectory is the SDK’s top-level output — one per conversation. It wraps the full multi-turn agent session into a single, structured object.| Field | Type | Description |
|---|---|---|
task | Task | Conversation metadata (ID, source, turn count, tokens, cost) |
steps | list[Step] | Ordered decision-point snapshots (one per turn) |
reward | Reward | Optional aggregate reward signal for the whole conversation |
metrics | TrajectoryMetrics | Token counts, tool call stats, error rates |
execution_metrics | ExecutionMetrics | Timing data (LLM time, total time) |
error | str | Error message if the conversation failed |
Step & Turn
A Turn is one user-to-agent exchange: the user sends a message, the agent may call tools, and the agent responds. Turns are the conceptual building block of a conversation. A Step is a Turn’s representation inside a Trajectory. Each Step contains the cumulative message history up to that point — not just the messages from that turn, but every message from the start of the conversation. This cumulative design means each Step is a self-contained training example: given this full context, here is what the agent did next. Step 1 would contain 4 messages (system, user, tool, assistant). Step 2 would contain all 4 messages from Step 1 plus the 4 new messages from Turn 2 — 8 messages total.Message
A Message is the atomic unit — a single piece of content in the conversation. Each Message has arole that identifies who produced it:
| Role | What it represents | Example |
|---|---|---|
system | System prompt | Instructions to the agent |
user | Human input | ”What’s the weather?” |
assistant | Model output (text or tool calls) | “It’s 62°F and foggy.” |
tool | Tool execution result | {"temp": 62} |
tool_calls list instead of (or in addition to) text content. The matching tool message carries a tool_response with the result or error.