What is Agent Trajectory?
Agent Trajectory is a structured, causally ordered record of the observable decisions, messages, tool proposals, policy outcomes, executions, observations, state transitions, approvals, errors, costs, and terminal outcome of one AI agent run.
Quick Facts
| Specification | Official Specification |
|---|
How It Works
Model Observable Events as a Causal Graph
Record model outputs, action proposals, policy decisions, Tool versions, redacted argument digests, executions, external effects, bounded observations, state transitions, approvals, errors, costs, and terminal reasons. Each event needs stable Run, Step, Parent, Call, Operation, Attempt, Schema, and Release identifiers. Parallel branches form a partial order, so wall-clock sorting alone can invent causality. OpenTelemetry supplies evolving technical conventions, but the task-level Trajectory should remain stable across telemetry vendors.
Evaluate the Path and the Environment Outcome
A final answer can be plausible while the agent used an unauthorized Tool, skipped evidence, duplicated a write, or failed to change the source system. Current [agent evaluation guidance](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) separates Task, Trial, Transcript or Trajectory, Grader, and Outcome. Combine deterministic order, argument, budget, authorization, and effect checks with calibrated rubric judges, repeated Trials, and an external Outcome oracle. Security-critical violations remain vetoes rather than small deductions from an average score.
Replay Without Repeating Effects or Secrets
Static replay feeds recorded observations into new orchestration or policy code; mock replay simulates Tools; live replay invokes current dependencies and can diverge, cost money, or repeat effects. NVIDIA's [Agent Trace Replay](https://docs.nvidia.com/dynamo/user-guides/agents/agent-simulation.md) deliberately replays serving workload shape without rerunning agent decisions or Tools, illustrating why replay semantics must be named. Redact before export, restrict Tenant access, record sampling and deletion, and never live-replay writes without Sandbox, idempotency, reconciliation, and explicit approval.
Key Characteristics
- Task-level causal event record distinct from chat transcript, raw logs, and distributed trace
- Observable proposals, policy decisions, calls, effects, observations, approvals, errors, and outcome
- Stable run, step, parent, call, operation, attempt, schema, and release identifiers
- Partial-order representation for parallel work rather than a fabricated total sequence
- Purpose-bound collection, pre-export redaction, tenant access control, retention, and deletion
- Single-step, path, and final-outcome evaluation with deterministic and calibrated judge methods
Common Use Cases
- Locating the first incorrect, unnecessary, denied, or unsafe step in a failed run
- Checking required authorization and evidence steps before a consequential write
- Comparing strict, unordered, subset, or superset tool-call paths across releases
- Building regression datasets from reviewed production failures without retaining secrets
- Attributing latency, token use, tool cost, retries, and cancellation to causal steps
- Replaying recorded observations against new orchestration or policy code in a sandbox
Example
Loading code...Frequently Asked Questions
How is an Agent Trajectory different from a trace or transcript?
A transcript contains visible messages. A distributed trace contains technical spans across services. A trajectory is the task-level behavioral record selected from runtime events and traces for debugging, evaluation, audit, and outcome analysis.
Should an Agent Trajectory contain chain-of-thought?
No. Record observable outputs, action proposals, policy decisions, tool calls, results, effects, and outcome. Hidden reasoning is unnecessary for most evaluation and creates privacy, security, and retention risk.
Can parallel agent steps be stored in one ordered list?
They can be serialized for storage, but evaluation should preserve parent and causal links. Wall-clock order alone can misrepresent concurrent branches, retries, and joins.
Can trajectories be replayed safely?
Static replay with recorded observations is safest. Live replay is non-deterministic and can repeat external effects, so it requires a sandbox, fixed versions, idempotency, and explicit approval for consequential operations.
How should Agent Trajectories be evaluated?
Combine deterministic policy and path checks, single-step evaluators, trajectory comparison or calibrated rubric judges, and verification of the final source-system outcome. Final-answer quality alone is insufficient.