The Hierarchy
A single agent conversation maps to this four-level hierarchy: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.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:
When the assistant invokes a tool, its message has a
tool_calls list instead of (or in addition to) text content. The matching tool message carries a tool_response with the result or error.