Traces, spans, and agents

A trace groups the model calls in one workflow or conversation. A span records one actual model attempt. An agent identifies the implementation making that call by a stable name and positive version.

Use client.session(model:tools:instructions:agent:) for a standalone call: its trace is named after the agent. Use withTrace for a grouped workflow, or startTrace for a conversation spanning UI events.

One attempt, one span

Successful, failed, and cancelled model attempts each produce a span. Parsing a response or updating UI does not add model spans. If the model succeeds and later application processing fails, the span remains successful while the trace can fail.

Spans form a flat collection. Retries are new attempts in the same trace; parallel calls retain their timing overlap. Provider tool activity remains in the full native capture. Each generation after a tool result records a new span with its own immutable prepared request. Framework or tool errors outside generation are recorded as session-failure spans with application context and providerCapture.failurePhase; these omit model input.

Identity and versions

Trace name/version describe the workflow. Agent name/version describe the model implementation: instructions, prompt construction, tools, and response schema. Increase a version when a change should be distinguishable in observations and evaluations. The SDK records identities; application code still owns execution.

Timing and outcome

A trace's model time starts at its earliest span and ends at the latest observed completion. Preparation and postprocessing are excluded; gaps between calls remain. An interrupted span has no invented end time or duration. Empty traces are not saved.

The API derives display outcomes such as partial success from span statuses while preserving the stored lifecycle status and original payload.

Original inputs and native capture

input holds original application arguments and is available on a trace or span. modelInput and modelOutput hold the provider's native data. providerCapture retains the full snapshot, including transcript and call boundaries when available. promptTemplate and outputReferences are optional application annotations.

These fields have separate purposes. Application processing and reference display never overwrite native model results. Omitted fields, explicit JSON null, and empty values remain distinguishable. See input capture.