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: ```python from latticeflow.core.dtypes import Trace ``` # Key Types **`TraceItem`** — A conversation item. One of: [`Message`](#message) | [`FunctionCall`](#functioncall) | [`FunctionCallOutput`](#functioncalloutput) | [`CustomTaskInputMessage`](#customtaskinputmessage) | [`CustomTaskOutputMessage`](#customtaskoutputmessage) **`TraceEvent`** — An execution event. One of: [`MessageEvent`](#messageevent) | [`FunctionCallEvent`](#functioncallevent) | [`ModelCallEvent`](#modelcallevent) | [`SpanBeginEvent`](#spanbeginevent) | [`SpanEndEvent`](#spanendevent) | [`CompactionEvent`](#compactionevent) | [`ErrorEvent`](#errorevent) | [`CustomEvent`](#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` ```python 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` ```python 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](#message), [FunctionCall](#functioncall), [FunctionCallOutput](#functioncalloutput), [CustomTaskInputMessage](#customtaskinputmessage), [CustomTaskOutputMessage](#customtaskoutputmessage)] required Items *** **`metadata`** [TraceMetadata](#tracemetadata) Default: `None`
*** **`events`** `array`[[MessageEvent](#messageevent), [FunctionCallEvent](#functioncallevent), [ModelCallEvent](#modelcallevent), [SpanBeginEvent](#spanbeginevent), [SpanEndEvent](#spanendevent), [CompactionEvent](#compactionevent), [ErrorEvent](#errorevent), [CustomEvent](#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`
## `OutputTextContent` A text output from the model. **Properties** *** **`type`** Literal "`output_text`" The type of the output text. Always `output_text`. Default: `output_text`
*** **`text`** `string` required The text output from the model. *** **`annotations`** `array`[[UrlCitationBody](#urlcitationbody), [TextCitationBody](#textcitationbody)] required The annotations of the text output. *** **`logprobs`** `array`[[LogProb](#logprob)] Logprobs Default: `None`
## `UrlCitationBody` A citation for a web resource used to generate a model response. **Properties** *** **`type`** Literal "`url_citation`" The type of the URL citation. Always `url_citation`. Default: `url_citation`
*** **`url`** `string` required The URL of the web resource. *** **`start_index`** `integer` required The index of the first character of the URL citation in the message. *** **`end_index`** `integer` required The index of the last character of the URL citation in the message. *** **`title`** `string` required The title of the web resource. ## `InputImageContent` An image input to the model. Learn about [image inputs](/docs/guides/vision). **Properties** *** **`type`** Literal "`input_image`" The type of the input item. Always `input_image`. Default: `input_image`
*** **`image_url`** `string` Image Url Default: `None`
*** **`detail`** enum ImageDetail required **Allowed Values:** - `low` - `high` - `auto` ## `ReasoningTextContent` Reasoning text from the model. **Properties** *** **`type`** Literal "`reasoning_text`" The type of the reasoning text. Always `reasoning_text`. Default: `reasoning_text`
*** **`text`** `string` required The reasoning text from the model. ## `RefusalContent` A refusal from the model. **Properties** *** **`type`** Literal "`refusal`" The type of the refusal. Always `refusal`. Default: `refusal`
*** **`refusal`** `string` required The refusal explanation from the model. ## `SummaryTextContent` A summary text from the model. **Properties** *** **`type`** Literal "`summary_text`" The type of the object. Always `summary_text`. Default: `summary_text`
*** **`text`** `string` required A summary of the reasoning output from the model so far. ## `TextCitationBody` A citation referencing a plain-text source (e.g. a retrieved knowledge-base chunk). **Properties** *** **`type`** Literal "`text_citation`" The type of the text citation. Always `text_citation`. Default: `text_citation`
*** **`content`** `string` required The text content of the cited source. ## `LogProb` The log probability of a token. **Properties** *** **`token`** `string` required Token *** **`logprob`** `number` required Logprob *** **`bytes`** `array`[`integer`] required Bytes *** **`top_logprobs`** `array`[[TopLogProb](#toplogprob)] required Top Logprobs ## `TopLogProb` The top log probability of a token. **Properties** *** **`token`** `string` required Token *** **`logprob`** `number` required Logprob *** **`bytes`** `array`[`integer`] required Bytes ## `InputVideoContent` A content block representing a video input to the model. **Properties** *** **`type`** Literal "`input_video`" The type of the input content. Always `input_video`. Default: `input_video`
*** **`video_url`** `string` required A base64 or remote url that resolves to a video file. ## `TextContent` A text content. **Properties** *** **`type`** Literal "`text`" Type Default: `text`
*** **`text`** `string` required Text ## `InputFileContent` A file input to the model. **Properties** *** **`type`** Literal "`input_file`" The type of the input item. Always `input_file`. Default: `input_file`
*** **`filename`** `string` The name of the file to be sent to the model. Default: `None`
*** **`file_url`** `string` The URL of the file to be sent to the model. Default: `None`
## `InputTextContent` A text input to the model. **Properties** *** **`type`** Literal "`input_text`" The type of the input item. Always `input_text`. Default: `input_text`
*** **`text`** `string` required The text input to the model. ## `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](#message), [CustomTaskInputMessage](#customtaskinputmessage), [CustomTaskOutputMessage](#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`, `array`[[InputTextContent](#inputtextcontent), [InputImageContent](#inputimagecontent), [InputFileContent](#inputfilecontent)] 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](#message), [FunctionCall](#functioncall), [FunctionCallOutput](#functioncalloutput), [CustomTaskInputMessage](#customtaskinputmessage), [CustomTaskOutputMessage](#customtaskoutputmessage)] required Input Context *** **`output_items`** `array`[[Message](#message), [FunctionCall](#functioncall), [FunctionCallOutput](#functioncalloutput), [CustomTaskInputMessage](#customtaskinputmessage), [CustomTaskOutputMessage](#customtaskoutputmessage)] required Output Items *** **`usage`** [ModelUsage](#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`[[InputTextContent](#inputtextcontent), [OutputTextContent](#outputtextcontent), [TextContent](#textcontent), [SummaryTextContent](#summarytextcontent), [ReasoningTextContent](#reasoningtextcontent), [RefusalContent](#refusalcontent), [InputImageContent](#inputimagecontent), [InputFileContent](#inputfilecontent), [InputVideoContent](#inputvideocontent)] 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`, `array`[[InputTextContent](#inputtextcontent), [InputImageContent](#inputimagecontent), [InputFileContent](#inputfilecontent)] 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.