Traces - Veval Docs

A trace records one run of your agent: its input, its output, every step in between, and the timing and cost of the whole run. Every call to RunAsync produces one trace, whether the agent succeeds or throws.

How traces fit in

A trace is made of steps. Your agent records a step for each LLM call or sub-operation it wraps in TrackStepAsync. Traces are the raw material for testing. A scenario item can replay a trace, replay uses a trace’s recorded outputs in place of live LLM calls, and a snapshot is saved from a known-good trace.

What a trace records

Field	Description
Trace ID	Unique ID for the run, prefixed `tr_`. Generated by the SDK.
Agent name	The name you pass to `RunAsync`. Identifies the agent in the dashboard.
Input	The optional input you pass to `RunAsync`.
Output	The value your agent returned.
Status	`success`, or `error` if your agent threw.
Error	The exception message when the status is `error`.
Timing	Start time, end time, and total duration.
Total cost	The sum of `cost_usd` across all steps.
Metadata	Key/value pairs you attach with `SetMetadata`.
Steps	Every step recorded during the run, in order.

Status

Status	Meaning
`success`	Your agent returned normally.
`error`	Your agent threw. The SDK records the error message, ships the trace, and rethrows.

Ingestion

The SDK sends the trace when the run finishes. Traces are ingested asynchronously, so a trace can take a moment to appear in the dashboard or be returned by GetTraceAsync.

Deep dives

Steps

What a step records and how steps are matched.

Instrument your agent

Record traces, steps, and metadata.