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
An Agent Trajectory answers what the system observed and did during one run. It is broader than a chat transcript, which contains user-visible messages, and narrower than a full distributed trace, which may include storage, network, queue, and infrastructure spans. A trajectory can be derived from traces and runtime events, but it should use a stable task-level schema rather than depend on one vendor's telemetry layout.
Trajectory does not mean hidden chain-of-thought. Store observable model outputs, structured action proposals, policy decisions, tool versions, redacted argument digests, execution and effect status, bounded observations, state transitions, approval records, usage, latency, errors, and terminal reasons. Do not require or retain private reasoning tokens. Natural-language summaries generated after the run are annotations, not authoritative events.
Every event needs stable run_id, step_id, event type, schema version, release identity, timestamp, and parent or causal links. Parallel branches form a partial order; sorting solely by wall-clock timestamp can invent a sequence that never occurred. Preserve call IDs, operation keys, attempt numbers, worker or provider identity where needed, and distinguish proposed, authorized, dispatched, committed, failed, cancelled, and outcome_unknown states.
Collect the minimum data needed for a declared purpose. Apply redaction before export, separate content from metadata, hash sensitive arguments when equality is sufficient, restrict access by tenant and role, encrypt stored payloads, define retention and deletion rules, and record sampling decisions. Tool results and retrieved content may contain prompt injection, secrets, personal data, or copyrighted material; telemetry storage is not a trust boundary.
Trajectory replay has several meanings. Static replay feeds recorded observations to new orchestration or policy code without invoking dependencies. Mock replay simulates tools. Live replay calls current models and tools and is non-deterministic, can incur cost, and may create side effects. Never live-replay writes without sandboxing, idempotency, and explicit approval. Pin model, prompt, tool schema, policy, dataset, and evaluator versions so comparisons remain interpretable.
Evaluate at three levels: single-step correctness, trajectory quality, and final environment outcome. Deterministic checks can enforce required-before-write order, forbidden tools, argument constraints, budget and approval rules, or compare strict, unordered, subset, and superset tool-call patterns. Rubric or model judges can assess adaptation and efficiency, but need calibration, blinded samples, disagreement handling, and deterministic vetoes for security rules. A correct final answer does not excuse an unauthorized, duplicate, or wasteful path.
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.