Trace

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. The Trace entity can be imported from:

from latticeflow.core.dtypes import Trace

Key Types

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

TraceEvent — An execution event. One of: MessageEvent | FunctionCallEvent | ModelCallEvent | SpanBeginEvent | SpanEndEvent | CompactionEvent | ErrorEvent | CustomEvent

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

from latticeflow.core.dtypes import (
    FunctionCall,
    FunctionCallOutput,
    FunctionCallOutputStatusEnum,
    FunctionCallStatus,
    InputTextContent,
    MessageStatus,
    OutputTextContent,
    Trace,
    TraceMetadata,
    UserMessage,
    AssistantMessage,
)

trace = Trace.from_items(
    items=[
        UserMessage(
            id="msg_1",
            status=MessageStatus.completed,
            content=[InputTextContent(text="What is the weather in Zurich?")],
        ),
        FunctionCall(
            id="fc_1",
            call_id="call_1",
            name="get_weather",
            arguments='{"city": "Zurich"}',
            status=FunctionCallStatus.completed,
        ),
        FunctionCallOutput(
            id="fco_1",
            call_id="call_1",
            output="15°C, partly cloudy",
            status=FunctionCallOutputStatusEnum.completed,
        ),
        AssistantMessage(
            id="msg_2",
            status=MessageStatus.completed,
            content=[OutputTextContent(text="It's 15°C and partly cloudy in Zurich.", annotations=[])],
        ),
    ],
    metadata=TraceMetadata(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

from latticeflow.core.dtypes import (
    AssistantMessage,
    FunctionCall,
    FunctionCallEvent,
    FunctionCallOutput,
    FunctionCallOutputStatusEnum,
    FunctionCallStatus,
    InputTextContent,
    MessageEvent,
    MessageStatus,
    ModelCallEvent,
    OutputTextContent,
    Trace,
    UserMessage,
)

user_msg = UserMessage(
    id="msg_1",
    status=MessageStatus.completed,
    content=[InputTextContent(text="What is the weather in Zurich?")],
)
fn_call = FunctionCall(
    id="fc_1",
    call_id="call_1",
    name="get_weather",
    arguments='{"city": "Zurich"}',
    status=FunctionCallStatus.completed,
)
fn_output = FunctionCallOutput(
    id="fco_1",
    call_id="call_1",
    output="15°C, partly cloudy",
    status=FunctionCallOutputStatusEnum.completed,
)
assistant_msg = AssistantMessage(
    id="msg_2",
    status=MessageStatus.completed,
    content=[OutputTextContent(text="It's 15°C and partly cloudy in Zurich.", annotations=[])],
)

trace = Trace.from_events(
    events=[
        MessageEvent(id="evt_1", item=user_msg),
        ModelCallEvent(
            id="evt_2",
            model="gpt-4o",
            input_context=[user_msg],
            output_items=[fn_call],
            tools=["get_weather"],
        ),
        FunctionCallEvent(
            id="evt_3",
            call_id="call_1",
            function="get_weather",
            arguments='{"city": "Zurich"}',
            result="15°C, partly cloudy",
            status=FunctionCallStatus.completed,
            model_call_id="evt_2",
        ),
        ModelCallEvent(
            id="evt_4",
            model="gpt-4o",
            input_context=[user_msg, fn_call, fn_output],
            output_items=[assistant_msg],
            tools=["get_weather"],
        ),
        MessageEvent(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

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

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

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

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

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 required

Result

status enum FunctionCallStatus required

Allowed Values:

  • in_progress
  • completed
  • incomplete

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

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

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

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

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

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

Allowed Values:

  • in_progress
  • completed
  • incomplete

role enum MessageRole required

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

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

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.