Data Flow
The SDK fetches raw traces from a provider, normalizes them into an intermediate format, builds a standardized Trajectory, and saves it as JSON.Trajectory
A Trajectory is the SDK’s core output — one per conversation. It contains everything about a multi-turn agent session in a structured, typed format.| Field | Type | Description |
|---|---|---|
task | Task | Conversation metadata (ID, source, turn count, tokens, cost) |
steps | list[Step] | Ordered sequence of decision points |
reward | Reward | Optional aggregate reward signal |
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 |
Turn
A Turn is one user-to-agent exchange: a user message, zero or more tool calls, and an assistant response. Internally the SDK groups traces into turns, then builds steps from them.Message
A Message is the atomic unit. Each has arole and optional content, tool calls, or tool responses.
| Role | What it represents | Example |
|---|---|---|
system | System prompt | Instructions to the agent |
user | Human input | ”What’s the weather?” |
assistant | Model output | ”It’s 62F and foggy.” |
tool | Tool execution result | {"temp": 62} |
tool_calls list. Tool messages carry a tool_response with the result (or error).
See the API Reference for full field definitions on all data models.