Conversations

Conversations preserve the evidence behind agent work after its sandbox is gone. They are read-only: new items are appended while work is running, but recorded model calls, tool calls, and messages are never rewritten.

Conversation versus task

A task is the execution session you control. It has a lifecycle, owns the sandbox, and can be prompted, steered, interrupted, cancelled, or resumed. A conversation is the record that execution leaves behind.

A conversation can contain several turns. Each turn produces a trace, and its items are GenAI spans — OpenTelemetry spans using the GenAI vocabulary, each capturing one model call, tool call, or agent invocation within that trace. The task points to the record through task.metadata.conversation_id.

Follow-up work belongs to another run on the task, and future behavior belongs to the recipe. The conversation remains an immutable source of evidence rather than a control surface for either one.

What a conversation records

Depending on what the agent used, the record can include:

• model inputs and outputs, including the system instructions and tool definitions that were in scope;
• tool calls, arguments, responses, status, and errors;
• root-agent and subagent activity, connected through their trace hierarchy;
• the model, provider, duration, token usage, and estimated cost of each call;
• lineage such as environment, runtime group, runtime version, experiment, and recipe commit.

The conversation resource aggregates this evidence into useful triage signals: start and end time, duration, traces, spans, token and cost totals, tool-use counts, and whether any item failed. The detail resource also carries the conversation’s complete agent index, without loading its span items.

Reading conversations over the API

The Conversations API separates the compact conversation resource (GET /v1/conversations, GET /v1/conversations/{id}) from its potentially large item stream (.../items, cursor-paginated GenAI spans, filterable to one agent lane with agent=root or an exact agent ID). Agent names are descriptive display metadata and can repeat within a conversation, so they are not item selectors — filter with agent=root or an exact agent ID. For offline analysis, a single .../export request returns one exhaustive representation — JSON, Arrow, Letta Trajectory , or turn-aware replay — selected by Accept media type, without pagination.

Read a whole conversation as one bundle:

introspection conversations get conv_123
introspection conversations get conv_123 --summary-only

const conversation = await runner.conversations.exportJson("conv_123");
const summary = await runner.conversations.get("conv_123");

To find the conversation an agent task produced, read task.metadata.conversation_id (for example from introspection tasks get <task-id>). For an agent task the conversation ID is the task ID unless metadata.conversation_id carries a caller-supplied ID, so reading the metadata pointer covers both cases.

See the API reference for the complete endpoints, schemas, filters, include expansions, and export media types.

Sharing and forks

A conversation can be shared through a read-only grant without transferring ownership or exposing the task itself. A recipient can inspect the record or fork a new, independent task from it to reproduce or challenge the result. The original conversation never changes. See State and artifacts.

Related concepts

• Tasks and runs: control the execution session that produces a conversation.
• Observations and patterns: move from one conversation to recurring behavior, and read feedback, observations, judgements, and other typed event records tied to agent activity.
• State and artifacts: share a conversation or fork new work from it.