Conversations

A conversation is the captured, replayable record of a task: every model call, tool call, and message, reconstructed from telemetry.

A conversation is the captured record of a task: the full sequence of model calls, tool calls, and messages, reconstructed from the telemetry the runtime emits as it runs. Conversations are immutable: a faithful account of what already happened, not a live session. They are the unit you investigate, judge, and experiment over.

Where a task is the execution, the conversation is the record. Every task leaves one behind, and that record is what the rest of the platform reasons about.

How it works

As a task runs, the runtime emits telemetry for everything the agent does. Introspection reconstructs that telemetry into a single ordered transcript so you can replay exactly what the agent saw and did, turn by turn.

A conversation is replayed item by item, in the style of Responses-API items. Each item captures one span of the transcript: the input messages new to that turn, the model’s output, the system instructions, and the tool definitions that were in scope. You can walk the transcript from the start, or load the state of the conversation as of any single item.

Conversations are read-only. You investigate and replay them, but you never mutate them. To change behavior, change the recipe and run again.

Structure

A conversation is an ordered list of items. Listing walks them in transcript order:

Each item is one span of work: typically an LLM turn (an assistant / chat operation) plus the tool calls and messages around it.
The list view of an item carries the turn-local delta: only the messages new to that turn.
The detail view of an item carries the full input history as of that point (the complete state the model saw) along with system instructions and tool definitions.

This lets you both scan the conversation as a sequence of turns and zoom into any single turn to see precisely what was sent to the model.

Querying and measuring

Each summary in the conversation list carries what you need to triage without opening the transcript: duration, turn and span counts, token totals (total_input_tokens, total_output_tokens, total_tokens), estimated cost (total_cost_usd), tool-call counts (tool_use_count, failed_tool_use_count), and the lineage the record is pinned to (environment, runtime_id, runtime_group_id, experiment_id, recipe_git_commit_sha). Individual items likewise carry a per-item cost_usd.

The list can be sorted by created (default), duration, turns, tokens, or cost, in either direction, and filtered by the same lineage fields plus request_model, agent name, status, service, and a time window — so “the ten most expensive conversations on this runtime version this week” is one list call, not a client-side scan.

For aggregates over many conversations, use the metrics API (POST /v1/metrics): one bounded query with allow-listed measures and dimensions that can count, sum, average, or take percentiles over conversations, spans, and events — for example p95 duration per runtime version, or token spend per experiment arm. The conversations view folds each conversation into one row first, so percentiles are taken over per-conversation totals rather than raw spans. See the API Reference for the full contract.

Conversation reads are bounded to recent data by default: lists scan the last few days unless you pass explicit start_date / end_date bounds, and item reads accept a lookback_days window (an old conversation’s items are still found — the read transparently widens once if the default window comes up empty).

Lists are cursor-paginated: each page returns up to 1000 rows (limit, default 100) plus an opaque next cursor. SDK iterators (for await, async for, or Rust’s Paginator) follow those cursors for you.

For large exports, conversation and event reads can return Apache Arrow IPC instead of JSON. Arrow keeps the same filtering and pagination but uses a compact columnar encoding; event pages include a payload struct typed to the requested family. It is optional—install the SDK’s Arrow dependency or feature only when you need bulk downloads. Customer track() and gen_ai.* telemetry remains measurable through POST /v1/metrics, not enumerable through /v1/events.

Tasks themselves are not shareable, but conversations and files are. A share is a read-only link to a conversation (or a file).

From a shared conversation you can fork a new task: start a fresh execution seeded from that record to reproduce a bug, retry a turn, or debug a failure path without touching the original. The original conversation stays immutable; the fork is a brand-new task with its own conversation.

What conversations feed

Conversations are the backbone of the understand-and-improve half of the operator loop:

They feed observations and patterns: when a conversation completes, the platform synthesizes observations about what happened and clusters them into recurring patterns.
They are graded by judges: each judge runs automatically over a completed conversation and records a pass / fail / not_applicable judgement.

Because the record is immutable and pinned to a runtime version, every observation, pattern, and judgement traces back to an exact, replayable conversation.

Tasks: the execution that produces a conversation.
Observations & patterns: what the platform notices across conversations.
Judges: the rubrics that grade each conversation.
Files & shares: what makes a conversation shareable and forkable.