> ## Documentation Index
> Fetch the complete documentation index at: https://tracevell.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Capture Agent Trajectories in Every Evaluation Trial

The trajectory is what your app did during a trial: its LLM calls and tool calls. Tracevell shows it under the trial's trace, next to the verifier's score, so a failing [agent evaluation](https://tracevell.com/docs/agent-evaluations/introduction.md) case takes one click to explain.

The trace is only as rich as what the app reports: without a trajectory you see the reward but not the calls behind it. How you capture it depends on whether the app is instrumented with Tracevell.

## Instrumented apps

If the app is instrumented with Tracevell (it calls `Laminar.initialize()`), there's nothing to convert.

During a run, the Tracevell plugin sets `LMNR_TRAJECTORY_PATH=/logs/agent/trajectory.json` in the agent's environment. When this variable is set, the SDK writes the app's spans to that file instead of sending them to Tracevell. The plugin then attaches them to the trial's trace: every LLM call with its tokens and cost, and tool calls as `TOOL` spans.

* The app needs no Tracevell API key and no network access to Tracevell.
* It works with the Python SDK (`lmnr` 0.8.4 and later) and the TypeScript SDK (`@lmnr-ai/lmnr` 0.8.54 and later).

## Apps without instrumentation

**If the app isn't instrumented, you can rebuild the trajectory from its own history.** Most products already store the conversation somewhere, for the UI, for audit, or as agent memory: message tables, run and step tables, LangGraph checkpointers, or JSONL transcripts. After the driver finishes, including when it ends as `failed` or `timeout` (a partial trajectory is often the most useful one), run an exporter that reads this case's history and writes `/logs/agent/trajectory.json` in Harbor's [ATIF](https://docs.harborframework.com/agents/atif) format:

```json /logs/agent/trajectory.json theme={null}
{
  "schema_version": "ATIF-v1.8",
  "agent": {"name": "support-agent", "version": "1.0", "model_name": "claude-sonnet-5"},
  "notes": "Rebuilt from the tickets and messages tables after the run.",
  "steps": [
    {"step_id": 1, "source": "user", "timestamp": "2026-11-03T10:15:02Z",
     "message": "I was charged twice for my October invoice. Can you refund one?"},
    {"step_id": 2, "source": "agent", "timestamp": "2026-11-03T10:15:05Z",
     "model_name": "claude-sonnet-5",
     "message": "Let me look at your charges.",
     "tool_calls": [{"tool_call_id": "call_1", "function_name": "list_charges",
                     "arguments": {"email": "maria.lopez@example.com"}}],
     "observation": {"results": [{"source_call_id": "call_1", "content": "3 charges found"}]}}
  ]
}
```

Every message is a step with a sequential `step_id`, a `source` (`user`, `agent`, or `system`), a `message`, and a timestamp. Tool calls and their results belong to the agent step that made them. Stored history usually lacks token counts and costs, so leave `metrics` out instead of estimating it, and use `notes` to say where the trajectory came from.

> [!TIP]
>
> Don't write a reconstructed trajectory for an instrumented app, or the agent's steps show up twice.

## Next steps

> [card] [Drive and grade a trial](https://tracevell.com/docs/agent-evaluations/production-harness.md#drive-the-entry-point)
>
> Write the driver and the verifier, and choose where the verifier runs.

> [card] [Read a failing trial](https://tracevell.com/docs/platform/viewing-traces.md)
>
> Open a low-scoring datapoint and read the app's run as a transcript.

> [card] [Track failures with Signals](https://tracevell.com/docs/signals/introduction.md)
>
> Detect a failure in production traces, then turn the flagged traces into cases.

> [card] [Troubleshooting](https://tracevell.com/docs/agent-evaluations/troubleshooting.md)
>
> Fixes for stale images, missing env vars, and empty traces.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.