A Trace represents a conversation between a user and an agent in the Open Responses format. It stores a sequence of items (messages, function calls, and function call outputs) and provides helper methods to extract turns, inspect function calls, and navigate multi-agent spans.

Key Types

TraceItem — A conversation item. One of: Message | FunctionCall | FunctionCallOutput | CustomTaskInputMessage | CustomTaskOutputMessage

Methods and Properties

Constructors

Trace.from_items(items, **kwargs) classmethod

Construct a Trace from conversation items only (no events). Use this for simple or single-agent traces where no execution metadata is needed.

Parameter	Type	Description
`items`	`list[TraceItem]`	Conversation items (messages, function calls, function call outputs).
`**kwargs`		Additional fields forwarded to the Trace constructor (e.g., `metadata`).

Returns: Trace

Example Trace with items

trace = {
    "items": [
        {
            "type": "message",
            "id": "msg_1",
            "role": "user",
            "status": "completed",
            "content": [{"type": "input_text", "text": "What is the weather in Zurich?"}],
        },
        {
            "type": "function_call",
            "id": "fc_1",
            "call_id": "call_1",
            "name": "get_weather",
            "arguments": '{"city": "Zurich"}',
            "status": "completed",
        },
        {
            "type": "function_call_output",
            "id": "fco_1",
            "call_id": "call_1",
            "output": "15°C, partly cloudy",
            "status": "completed",
        },
        {
            "type": "message",
            "id": "msg_2",
            "role": "assistant",
            "status": "completed",
            "content": [{"type": "output_text", "text": "It's 15°C and partly cloudy in Zurich.", "annotations": []}],
        },
    ],
    "metadata": {"agent": "weather-agent", "model": "gpt-4o"},
}

Trace.from_events(events, *, span_id=None, **kwargs) classmethod

Construct a Trace from an event stream. Items are derived automatically from the events. If any MessageEvent is present, items are derived from message and function call events. Otherwise, items are reconstructed from ModelCallEvent records.

Parameter	Type	Description
`events`	`list[TraceEvent]`	Execution event stream.
`span_id`	`str \| None`	Span to scope the Trace to. `None` for a root Trace.
`**kwargs`		Additional fields forwarded to the Trace constructor.

Returns: Trace

Example Trace with events

user_msg = {
    "type": "message",
    "id": "msg_1",
    "role": "user",
    "status": "completed",
    "content": [{"type": "input_text", "text": "What is the weather in Zurich?"}],
}
fn_call = {
    "type": "function_call",
    "id": "fc_1",
    "call_id": "call_1",
    "name": "get_weather",
    "arguments": '{"city": "Zurich"}',
    "status": "completed",
}
fn_output = {
    "type": "function_call_output",
    "id": "fco_1",
    "call_id": "call_1",
    "output": "15°C, partly cloudy",
    "status": "completed",
}
assistant_msg = {
    "type": "message",
    "id": "msg_2",
    "role": "assistant",
    "status": "completed",
    "content": [{"type": "output_text", "text": "It's 15°C and partly cloudy in Zurich.", "annotations": []}],
}

trace = {
    "events": [
        {"type": "message_event", "id": "evt_1", "item": user_msg},
        {
            "type": "model_call_event",
            "id": "evt_2",
            "model": "gpt-4o",
            "input_context": [user_msg],
            "output_items": [fn_call],
            "tools": ["get_weather"],
        },
        {
            "type": "function_call_event",
            "id": "evt_3",
            "call_id": "call_1",
            "function": "get_weather",
            "arguments": '{"city": "Zurich"}',
            "result": "15°C, partly cloudy",
            "status": "completed",
            "model_call_id": "evt_2",
        },
        {
            "type": "model_call_event",
            "id": "evt_4",
            "model": "gpt-4o",
            "input_context": [user_msg, fn_call, fn_output],
            "output_items": [assistant_msg],
            "tools": ["get_weather"],
        },
        {"type": "message_event", "id": "evt_5", "item": assistant_msg, "model_call_id": "evt_4"},
    ],
}

Properties

turns list[Turn]

Conversation turns extracted from the trace. Each Turn starts with a user message and includes all subsequent items until the next user message or end of the trace.

A Turn has the following fields and properties:

Field / Property	Type	Description
`user_message`	`UserMessage`	The user message that initiates this turn.
`assistant_items`	`list[TraceItem]`	All items following the user message (assistant messages, function calls, function outputs).
`assistant_messages`	`list[AssistantMessage]`	All assistant messages in this turn (property).
`function_calls`	`list[FunctionCall]`	All function calls in this turn (property).
`function_outputs`	`list[FunctionCallOutput]`	All function call outputs in this turn (property).
`function_call_pairs`	`list[tuple[FunctionCall, FunctionCallOutput \| None]]`	Pairs of (call, output) matched by `call_id` (property).

preamble list[TraceItem]

All items before the first user message (system messages, assistant greetings, initial function calls).

conversation_items list[TraceItem]

All items from the first user message onward (excludes preamble).

system_messages list[SystemMessage]

All system messages in the preamble, in order.

function_calls list[FunctionCall]

All function calls across the trace (excluding preamble), in order.

function_outputs list[FunctionCallOutput]

All function call outputs across the trace (excluding preamble), in order.

assistant_messages list[AssistantMessage]

All assistant messages across the trace (excluding preamble), in order.

user_messages list[UserMessage]

All user messages across the trace, in order.

Instance Methods

spans() list[Trace]

Return immediate child spans as Trace objects. Each child span has its own items, events, and span metadata (span_id, span_name, span_type). Call .spans() on a child recursively to walk sub-agent spans. Returns an empty list if there are no events.

get_function_calls_by_name(name) list[FunctionCall]

Return all function calls with the given function name (excluding preamble).

Parameter	Type	Description
`name`	`str`	Function name to filter by.

get_function_output_for_call(call_id) FunctionCallOutput | None

Return the function output matching a given call_id (excluding preamble), or None if not found.

Parameter	Type	Description
`call_id`	`str`	The `call_id` of the function call to look up.

get_function_call_pairs() list[tuple[FunctionCall, FunctionCallOutput | None]]

Return all (function_call, function_output) pairs matched by call_id, in order (excluding preamble).

get_last_assistant_text() str | None

Return the text content of the last assistant message (excluding preamble), or None if there are no assistant messages.

get_last_user_text() str | None

Return the text content of the last user message, or None if there are no user messages.

get_first_system_prompt() str | None

Return the text of the first system message in the preamble, or None if there are no system messages.

get_function_call_arguments(call) dict

Parse and return the JSON arguments of a function call.

Parameter	Type	Description
`call`	`FunctionCall`	The function call whose arguments to parse.

get_function_output_text(output) str

Extract the text content from a function call output.

Parameter	Type	Description
`output`	`FunctionCallOutput`	The function call output to extract text from.

Trace Overview

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

Conversation items in Open Responses format (messages, function calls, function call outputs).

metadata TraceMetadata

Optional trace-level metadata (identity, provenance, timing, outcome).

Default: None

events array[MessageEvent , FunctionCallEvent , ModelCallEvent , SpanBeginEvent , SpanEndEvent , CompactionEvent , ErrorEvent , CustomEvent ]

Optional execution event stream for multi-agent traces. None for legacy single-agent traces.

Default: None

span_id string

Span identifier when this Trace represents a child span extracted by spans(). None on root traces.

Default: None

span_name string

Human-readable name of the span (e.g. agent name). None on root traces.

Default: None

span_type string

Span classification ("agent", "function_call", etc.). None on root traces.

Default: None

Definitions

`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

Unique trace identifier.

Default: None

source_type string

Origin system, e.g. "latticeflow", "inspect_ai", "claude_code".

Default: None

source_uri string

URI for the source data (file path, URL, etc.).

Default: None

agent string

Agent name.

Default: None

model string

Primary model used.

Default: None

tags array[string]

User-defined tags, e.g. ["jailbreak", "multi-turn"].

Default: None

created_at string

When the trace was created.

Default: None

total_time number

Wall-clock execution time in seconds.

Default: None

total_tokens integer

Total tokens (input + output) across all model calls.

Default: None

message_count integer

Total number of conversation messages.

Default: None

error string

Error message if the trace terminated with an error.

Default: None

extra object

Catch-all for domain-specific metadata not covered by the typed fields.

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

Unique identifier for the event. Auto-generated at creation time. Used for cross-referencing events (e.g. linking a message back to the model call that produced it).

span_id string

The span this event belongs to. None for root-level events.

Default: None

timestamp string

When the event occurred. None is allowed for imported events where timing is unknown.

Default: None

metadata object

Arbitrary per-event key-value data for source-specific fields that don't have dedicated typed fields.

Default: None

type Literal "message_event"

Event type discriminator.

Default: message_event

item Message , CustomTaskInputMessage , CustomTaskOutputMessage required

The conversation item that was added.

model_call_id string

ID of the ModelCallEvent that produced this message, or None for static messages (system prompts, user messages from templates, loaded traces).

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

Unique identifier for the event. Auto-generated at creation time. Used for cross-referencing events (e.g. linking a message back to the model call that produced it).

span_id string

The span this event belongs to. None for root-level events.

Default: None

timestamp string

When the event occurred. None is allowed for imported events where timing is unknown.

Default: None

metadata object

Arbitrary per-event key-value data for source-specific fields that don't have dedicated typed fields.

Default: None

type Literal "function_call_event"

Event type discriminator.

Default: function_call_event

call_id string required

Unique ID of the function call (matches FunctionCall.call_id).

function string required

Name of the function that was called.

arguments string required

JSON string of arguments (matches FunctionCall.arguments).

result string required

The function's return value (matches FunctionCallOutput.output).

status enum FunctionCallStatus required

Execution status of the function call.

Possible FunctionCallStatus values

Allowed Values:

in_progress
completed
incomplete

working_time number

Execution duration in seconds.

Default: None

error string

Error message if the function call failed.

Default: None

agent string

Sub-agent name if this tool call spawned a sub-agent (handoff).

Default: None

agent_span_id string

ID of the sub-agent's SpanBeginEvent that points from this event to the span.

Default: None

model_call_id string

ID of the ModelCallEvent that requested this call, or None when triggered programmatically.

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

Unique identifier for the event. Auto-generated at creation time. Used for cross-referencing events (e.g. linking a message back to the model call that produced it).

span_id string

The span this event belongs to. None for root-level events.

Default: None

timestamp string

When the event occurred. None is allowed for imported events where timing is unknown.

Default: None

metadata object

Arbitrary per-event key-value data for source-specific fields that don't have dedicated typed fields.

Default: None

type Literal "model_call_event"

Event type discriminator.

Default: model_call_event

model string required

Name of the model that was called.

input_context array[Message , FunctionCall , FunctionCallOutput , CustomTaskInputMessage , CustomTaskOutputMessage ] required

Actual context sent to the model.

output_items array[Message , FunctionCall , FunctionCallOutput , CustomTaskInputMessage , CustomTaskOutputMessage ] required

What the model produced (messages and/or function calls).

usage ModelUsage

Token usage for this call.

Default: None

tools array[string]

Names of the tools available during this call.

Default: None

total_time number

Call duration in seconds.

Default: None

error string

Error message if the call failed.

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

Unique identifier for the event. Auto-generated at creation time. Used for cross-referencing events (e.g. linking a message back to the model call that produced it).

span_id string required

Unique span ID. Referenced by SpanEndEvent.span_id to close the span and by FunctionCallEvent.agent_span_id for handoff links.

timestamp string

When the event occurred. None is allowed for imported events where timing is unknown.

Default: None

metadata object

Arbitrary per-event key-value data for source-specific fields that don't have dedicated typed fields.

Default: None

type Literal "span_begin"

Event type discriminator.

Default: span_begin

parent_span_id string

Parent span ID, or None if this span is at root level.

Default: None

name string required

Human-readable name for the span (agent name, tool name, etc.).

span_type string

Classification: "agent" for autonomous sub-agents, "function_call" for tool execution wrappers, or None for structural groupings.

Default: None

`SpanEndEvent`

Marks the end of a named execution span.

Properties

id string

Unique identifier for the event. Auto-generated at creation time. Used for cross-referencing events (e.g. linking a message back to the model call that produced it).

span_id string required

The span ID being closed. Must match a preceding SpanBeginEvent.span_id.

timestamp string

When the event occurred. None is allowed for imported events where timing is unknown.

Default: None

metadata object

Arbitrary per-event key-value data for source-specific fields that don't have dedicated typed fields.

Default: None

type Literal "span_end"

Event type discriminator.

Default: span_end

`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

Unique identifier for the event. Auto-generated at creation time. Used for cross-referencing events (e.g. linking a message back to the model call that produced it).

span_id string

The span this event belongs to. None for root-level events.

Default: None

timestamp string

When the event occurred. None is allowed for imported events where timing is unknown.

Default: None

metadata object

Arbitrary per-event key-value data for source-specific fields that don't have dedicated typed fields.

Default: None

type Literal "compaction"

Event type discriminator.

Default: compaction

strategy string required

How the context was compacted: "summary" replaces it with a shorter version, "trim" drops messages from the front.

tokens_before integer

Token count before compaction.

Default: None

tokens_after integer

Token count after compaction.

Default: None

`ErrorEvent`

Records an error that occurred during execution.

Properties

id string

Unique identifier for the event. Auto-generated at creation time. Used for cross-referencing events (e.g. linking a message back to the model call that produced it).

span_id string

The span this event belongs to. None for root-level events.

Default: None

timestamp string

When the event occurred. None is allowed for imported events where timing is unknown.

Default: None

metadata object

Arbitrary per-event key-value data for source-specific fields that don't have dedicated typed fields.

Default: None

type Literal "error"

Event type discriminator.

Default: error

message string required

Human-readable error description.

traceback string

Full traceback, if available.

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

Unique identifier for the event. Auto-generated at creation time. Used for cross-referencing events (e.g. linking a message back to the model call that produced it).

span_id string

The span this event belongs to. None for root-level events.

Default: None

timestamp string

When the event occurred. None is allowed for imported events where timing is unknown.

Default: None

metadata object

Arbitrary per-event key-value data for source-specific fields that don't have dedicated typed fields.

Default: None

type Literal "custom"

Event type discriminator.

Default: custom

name string required

Event name, e.g. "sandbox", "approval", "my_metric".

data object required

Arbitrary structured payload.

`ModelUsage`

Token usage statistics for a model inference call.

Properties

num_completion_tokens integer

The number of completion tokens used.

Default: None

num_prompt_tokens integer

The number of prompt tokens used.

Default: None

`Message`

A message to or from the model.

Properties

type Literal "message"

The type of the message. Always set to message.

Default: message

id string required

The unique ID of the message.

status enum MessageStatus required

Possible MessageStatus values

Allowed Values:

in_progress
completed
incomplete

role enum MessageRole required

Possible MessageRole values

Allowed Values:

user
assistant
system
developer

content array[null] required

The content of the message

`FunctionCall`

A function tool call that was generated by the model.

Properties

type Literal "function_call"

The type of the item. Always function_call.

Default: function_call

id string required

The unique ID of the function call item.

call_id string required

The unique ID of the function tool call that was generated.

name string required

The name of the function that was called.

arguments string required

The arguments JSON string that was generated.

status enum FunctionCallStatus required

Possible FunctionCallStatus values

Allowed Values:

in_progress
completed
incomplete

`FunctionCallOutput`

A function tool call output that was returned by the tool.

Properties

type Literal "function_call_output"

The type of the function tool call output. Always function_call_output.

Default: function_call_output

id string required

The unique ID of the function tool call output. Populated when this item is returned via API.

call_id string required

The unique ID of the function tool call generated by the model.

output string required

Output

status enum FunctionCallOutputStatusEnum required

Possible FunctionCallOutputStatusEnum values

Similar to FunctionCallStatus. All three options are allowed here for compatibility, but because in practice these items will be provided by developers, only completed should be used.

Allowed Values:

in_progress
completed
incomplete

`CustomTaskInputMessage`

A custom task input item carrying an opaque user-defined payload.

Properties

type Literal "custom_task_input_message"

Type

Default: custom_task_input_message

content Any required

The opaque user-defined payload.

`CustomTaskOutputMessage`

A custom task output item carrying an opaque user-defined payload.

Properties

type Literal "custom_task_output_message"

Type

Default: custom_task_output_message

content Any required

The opaque user-defined payload.