Agent Trajectory Observability

Agent trajectory observability is the instrumentation needed to reconstruct how an agent moved from input and selected context to model decisions, tool calls, verification, and external effects. It extends ordinary application tracing with agent-specific operations such as memory search, context compaction, planning, subagent delegation, and skill execution.

The goal is causal inspection. Product analytics may report that a tool ran three times. A trajectory should show which memory was retrieved, which model call requested the tool, which result changed the plan, and whether the intended effect actually occurred.

Trace structure

OpenTelemetry traces organize work through trace identifiers, spans, parent-child relationships, events, attributes, status, and links for asynchronous causality. An agent run can map onto that substrate:

agent turn
├─ context assembly
│  ├─ memory route
│  ├─ retrieval
│  └─ compaction lookup
├─ model inference
├─ tool execution
├─ verification
└─ external effect
   ↔ provider receipt or reconciliation

OpenTelemetry's Generative AI semantic conventions are still marked as development work. They currently define operations including invoke_agent, plan, execute_tool, retrieval, search_memory, create_memory, and update_memory, along with model, conversation, prompt, usage, and error attributes. Those names provide a useful interoperability base, but they are not a finished agent-governance model.

Memory lineage

Memory-aware traces should retain strong context references rather than copying complete private artifacts into every span. For a retrieval, useful metadata includes:

• store and source identifier;
• query or query digest;
• selected record versions;
• ranking or route decision;
• permission boundary;
• compacted versus raw source;
• whether the retrieved state entered the model prompt.

For a memory write, the trace should connect the source event, proposed revision, reviewer or policy, resulting version, and rollback reference.

Causality beyond a tree

Agent work is not always a single synchronous call tree. A scheduled task may enqueue an outbox item that another process delivers. A subagent may produce an artifact used in a later turn. A provider timeout may be reconciled through a subsequent read.

Span links and provenance relations can represent these non-parental dependencies. The W3C PROV model adds vocabulary for entities, activities, derivations, association, attribution, and delegation. OpenTelemetry records operational timing; provenance records how artifacts and responsibility relate. The two views overlap without being identical.

Receipts and actual effects

A successful tool return is not always the final effect. External operations need provider receipts, read-after-write checks, or later reconciliation. The trace should distinguish:

• request constructed;
• authorization granted;
• execution attempted;
• provider accepted;
• effect observed;
• result unknown;
• retry or compensation performed.

This is especially important for durable agent execution, where retries after a timeout can duplicate an effect if the original result is unknown.

Privacy

Prompts, retrieved memories, tool arguments, and message bodies routinely contain sensitive information. Full content should not be the default telemetry payload. Prefer stable identifiers, digests, redacted summaries, byte lengths, schema names, and pointers to separately governed storage.

The OpenTelemetry Generative AI conventions explicitly mark prompt and message content as opt-in and warn that it may contain user or personally identifiable information. Trace context propagated between services should correlate operations rather than smuggle private memory through headers.

What trajectories enable

Trajectory observability supports:

• debugging a wrong or missing memory retrieval;
• measuring which context changed an answer;
• comparing model or harness versions on the same task;
• locating policy and adapter boundaries;
• evaluating compaction across long runs;
• proving that a public effect received an external receipt;
• identifying redundant subagent work;
• preserving the evidence for later self-improvement.

It does not make hidden reasoning fully legible or prove that a textual explanation caused an action. It makes the system's observable state transitions and artifact dependencies available for inspection.