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 capture the model and tool activity 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.

Read a conversation through the API

The Conversations API separates the compact conversation resource from its potentially large item stream:

The detail resource exposes agent IDs before you fetch items:

{
  "object": "conversation",
  "id": "conv_123",
  "created_at": "2026-08-07T20:00:00Z",
  "updated_at": "2026-08-07T20:01:00Z",
  "agents": [
    {
      "id": "agent_root_123",
      "name": "coordinator",
      "depth": 0
    },
    {
      "id": "agent_research_456",
      "name": "researcher",
      "parent_id": "agent_root_123",
      "invocation_id": "invoke_456",
      "depth": 1
    }
  ],
  "usage": {
    "input_tokens": 100,
    "output_tokens": 40,
    "total_tokens": 140
  },
  "cost": { "usd": 0.01 },
  "metrics": {
    "duration_ms": 60000,
    "trace_count": 3,
    "span_count": 18,
    "tool_use_count": 5,
    "failed_tool_use_count": 0,
    "has_errors": false
  }
}

Use the agent query parameter on the items endpoint to select an agent lane:

• omit agent to return items from every agent;
• pass agent=root to return only depth-zero root-agent items;
• pass an exact ID from agents[].id to return only that agent’s items.

Agent names are descriptive and can repeat, so they are not item selectors. Follow the opaque next cursor until has_more is false; do not construct or modify cursor values. Optional include values expand otherwise omitted item payloads such as system instructions, tool definitions, events, and raw span or resource attributes.

For agent debugging and offline analysis, request an exhaustive export. The server follows every internal item cursor, decrypts authorized fields, and returns one complete representation without pagination headers:

GET /v1/conversations/{conversation_id}/export
Accept: application/vnd.apache.arrow.stream

GET /v1/conversations/{conversation_id}/export
Accept: application/vnd.letta.trajectory+json;version=1

GET /v1/conversations/{conversation_id}/export?agent=root
Accept: application/vnd.introspection.conversation-replay+json;version=1

Arrow is a typed IPC stream suitable for columnar analysis. Trajectory v1 is a chronological JSON record array suitable for judging and debugging. The replay representation is specifically for conversations produced by the managed Recipe runtime. It carries that same strict trajectory plus canonical platform turn metadata: each turn is identified by its trace ID, points to its exact trajectory record range and original user-prompt records, and becomes complete when the runtime’s ended, parentless invoke_agent span has been exported. Error status still counts as completed; completion means ended, not successful. Generic GenAI conversations without that root wrapper are not replay-eligible. Model and tool spans within the trace are steps; they do not create additional turns. These formats include system instructions, tool definitions, events, resource attributes, and span attributes automatically. Add agent=root or one exact agent ID to narrow either export.

The CLI reads a whole conversation as one bundle: the conversation resource, every item page, and the conversation’s feedback events composed together. To find the conversation produced by an agent task, read task.metadata.conversation_id, for example from introspection tasks get <task-id>. Task and conversation IDs are distinct; do not pass the task ID as the conversation ID.

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

--summary-only returns just the conversation resource, without its items.

See the complete schemas, filters, and response envelopes in the API reference.

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: read feedback, observations, judgements, and other typed event records tied to agent activity.
• Observations and patterns: move from one conversation to recurring behavior.
• State and artifacts: share a conversation or fork new work from it.