Traces
BaseTraceEvent
Base class for all trace events, providing common metadata fields.
Properties
id string
Id
span_id string
Span Id
Default: None
timestamp string
Timestamp
Default: None
metadata object
Metadata
Default: None
CompactionEvent
Records a compaction boundary where the conversation context was shortened.
After this event the next ModelCallEvent.input_context will reflect the compacted context rather than the full history.
Properties
id string
Id
span_id string
Span Id
Default: None
timestamp string
Timestamp
Default: None
metadata object
Metadata
Default: None
type Literal “compaction”
Type
Default: compaction
strategy string required
Strategy
tokens_before integer
Tokens Before
Default: None
tokens_after integer
Tokens After
Default: None
CustomEvent
A fallback event type for arbitrary structured data.
Serves as an escape hatch for event types not yet modelled (e.g. SandboxEvent, ApprovalEvent from inspect-ai), custom solver instrumentation, and forward compatibility with new external event types.
Properties
id string
Id
span_id string
Span Id
Default: None
timestamp string
Timestamp
Default: None
metadata object
Metadata
Default: None
type Literal “custom”
Type
Default: custom
name string required
Name
data object required
Data
ErrorEvent
Records an error that occurred during execution.
Properties
id string
Id
span_id string
Span Id
Default: None
timestamp string
Timestamp
Default: None
metadata object
Metadata
Default: None
type Literal “error”
Type
Default: error
message string required
Message
traceback string
Traceback
Default: None
FunctionCallEvent
Records a tool call lifecycle as a single event.
Absorbs what was previously two items (FunctionCall + FunctionCallOutput) into one event with execution metadata.
Properties
id string
Id
span_id string
Span Id
Default: None
timestamp string
Timestamp
Default: None
metadata object
Metadata
Default: None
type Literal “function_call_event”
Type
Default: function_call_event
call_id string required
Call Id
function string required
Function
arguments string required
Arguments
result string, array[InputTextContent, InputImageContent, InputFileContent] required
Result
status FunctionCallStatus required
working_time number
Working Time
Default: None
error string
Error
Default: None
agent string
Agent
Default: None
agent_span_id string
Agent Span Id
Default: None
model_call_id string
Model Call Id
Default: None
MessageEvent
Records that a conversation item was added to the trace.
This is the incremental conversation record — each message (user, assistant, system) gets its own event.
Properties
id string
Id
span_id string
Span Id
Default: None
timestamp string
Timestamp
Default: None
metadata object
Metadata
Default: None
type Literal “message_event”
Type
Default: message_event
item Message, CustomTaskInputMessage, CustomTaskOutputMessage required
Item
model_call_id string
Model Call Id
Default: None
ModelCallEvent
Records a model API call with the full input context, output, and metadata.
input_context captures the actual context window at each model call.
Properties
id string
Id
span_id string
Span Id
Default: None
timestamp string
Timestamp
Default: None
metadata object
Metadata
Default: None
type Literal “model_call_event”
Type
Default: model_call_event
model string required
Model
input_context array[Message, FunctionCall, FunctionCallOutput, CustomTaskInputMessage, CustomTaskOutputMessage] required
Input Context
output_items array[Message, FunctionCall, FunctionCallOutput, CustomTaskInputMessage, CustomTaskOutputMessage] required
Output Items
usage ModelUsage
Default: None
tools array[string]
Tools
Default: None
total_time number
Total Time
Default: None
error string
Error
Default: None
SpanBeginEvent
Marks the beginning of a named execution span.
Spans define hierarchical boundaries for agents, tools, and other execution phases.
Properties
id string
Id
span_id string required
Span Id
timestamp string
Timestamp
Default: None
metadata object
Metadata
Default: None
type Literal “span_begin”
Type
Default: span_begin
parent_span_id string
Parent Span Id
Default: None
name string required
Name
span_type string
Span Type
Default: None
SpanEndEvent
Marks the end of a named execution span.
Properties
id string
Id
span_id string required
Span Id
timestamp string
Timestamp
Default: None
metadata object
Metadata
Default: None
type Literal “span_end”
Type
Default: span_end
Trace
Represents a conversation trace between a user and an agent.
A trace stores a sequence of items in the Open Responses format, including user messages, assistant messages, function calls, and function call outputs. It provides helper methods to extract individual turns, find function calls, and inspect the conversation.
The preamble property exposes everything before the first user message (system messages, assistant greetings, initial function calls, etc.). Everything from the first user message onward is accessible via turns.
For multi-agent traces, an optional events field provides a richer execution record with span markers encoding agent hierarchy. Use Trace.from_events() to construct event-based traces; items is derived automatically.
Properties
FORMAT string
Format
Default: open_responses
items array[Message, FunctionCall, FunctionCallOutput, CustomTaskInputMessage, CustomTaskOutputMessage] required
Items
metadata TraceMetadata
Default: None
events array[MessageEvent, FunctionCallEvent, ModelCallEvent, SpanBeginEvent, SpanEndEvent, CompactionEvent, ErrorEvent, CustomEvent]
Events
Default: None
span_id string
Span Id
Default: None
span_name string
Span Name
Default: None
span_type string
Span Type
Default: None
Computed Properties
assistant_messages list[AssistantMessage]
Return all assistant messages across the trace (excluding preamble).
conversation_items list[TraceItem]
Return items from the first user message onward (excludes preamble).
function_calls list[FunctionCall]
Return all function calls across the trace (excluding preamble).
function_outputs list[FunctionCallOutput]
Return all function call outputs across the trace (excluding preamble).
preamble list[TraceItem]
Return all items before the first user message.
system_messages list[SystemMessage]
Return all system messages in the preamble in order.
turns list[Turn]
Extract individual conversation turns.
user_messages list[UserMessage]
Return all user messages across the entire trace.
Methods
from_events classmethod
from_events(events: list[TraceEvent], *, span_id: str | None = None, **kwargs: Any) -> TraceConstruct a Trace from an event stream.
span_id identifies which span the Trace represents. Defaults to None for a root Trace; pass a span id when constructing a Trace for a specific span.
The item-derivation strategy is picked from the event stream itself:
- If any
MessageEventis present, items come from direct-spanMessageEventandFunctionCallEventvalues (native LF traces). - Otherwise, items are reconstructed from direct-span
ModelCallEvent. This path handles event streams imported from inspect-ai-style event streams that don’t produceMessageEvents.
from_items classmethod
from_items(items: list[TraceItem], **kwargs: Any) -> TraceConstruct a Trace from conversation items only (no events).
Use this for simple or legacy single-agent traces where no execution metadata is needed.
get_first_system_prompt method
get_first_system_prompt() -> str | NoneReturn the text of the first system message, if any.
get_function_call_arguments method
get_function_call_arguments(call: FunctionCall) -> dictParse and return the JSON arguments of a function call.
get_function_call_pairs method
get_function_call_pairs() -> list[tuple[FunctionCall, FunctionCallOutput | None]]Return all (function_call, function_output) pairs matched by call_id.
get_function_calls_by_name method
get_function_calls_by_name(name: str) -> list[FunctionCall]Return all function calls with the given function name.
get_function_output_for_call method
get_function_output_for_call(call_id: str) -> FunctionCallOutput | NoneReturn the function output matching a given call_id, if any.
get_function_output_text method
get_function_output_text(output: FunctionCallOutput) -> strExtract the text content from a function call output.
get_last_assistant_text method
get_last_assistant_text() -> str | NoneReturn the text content of the last assistant message, if any.
get_last_user_text method
get_last_user_text() -> str | NoneReturn the text of the last user message, if any.
spans method
spans() -> list[Trace]Return immediate child spans as Trace objects, or an empty list if there are no child spins.
Each child span is a Trace with its own items, events, and span metadata. Spans are returned in chronological order (matching the event stream order). Call .spans() on a child recursively to get sub-sub-agent spans.
TraceMetadata
Trace-level metadata capturing identity, provenance, and summary information.
All fields are optional. Only the trace data itself (items/events) is required. Metadata enriches the trace for filtering, grouping, and analysis.
Properties
trace_id string
Trace Id
Default: None
source_type string
Source Type
Default: None
source_uri string
Source Uri
Default: None
agent string
Agent
Default: None
model string
Model
Default: None
tags array[string]
Tags
Default: None
created_at string
Created At
Default: None
total_time number
Total Time
Default: None
total_tokens integer
Total Tokens
Default: None
message_count integer
Message Count
Default: None
error string
Error
Default: None
extra object
Extra
Default: None
Turn
A single conversational turn initiated by a user message.
A turn starts with a user message and includes all subsequent items until the next user message (or end of trace). This typically includes: - The user message itself - Zero or more assistant actions (function calls, function outputs, assistant messages) that form the response to the user message.
Properties
user_message UserMessage required
assistant_items array[Message, FunctionCall, FunctionCallOutput, CustomTaskInputMessage, CustomTaskOutputMessage] required
Assistant Items
Computed Properties
assistant_messages list[AssistantMessage]
Return all assistant messages in this turn in order.
function_call_pairs list[tuple[FunctionCall, FunctionCallOutput | None]]
Return pairs of (function_call, function_output) matched by call_id.
function_calls list[FunctionCall]
Return all function calls in this turn in order.
function_outputs list[FunctionCallOutput]
Return all function call outputs in this turn in order.