Native trace schema & compatibility¶
Generic workflows and decision stages use this same native schema. See workflow tracing for their versioned metadata contract.
AgentLoop's serialized trace JSON is a public compatibility surface: the CLI,
the HTTP API, both persistence backends, and the OTLP/Vercel adapters all read
and write it through one contract defined in agentloop/schema.py.
This document is the reference for that contract and how it evolves.
Versioning¶
Every trace serialized by AgentTrace.to_dict() / export_json() carries a
schema_version string:
{
"schema_version": "1.0",
"name": "research-agent",
"run_id": "run_1a2b3c…",
"started_at": "2026-01-01T00:00:00+00:00",
"ended_at": "2026-01-01T00:00:07+00:00",
"elapsed_ms": 7000.0,
"metadata": {},
"events": [ … ]
}
The version is MAJOR.MINOR:
- MAJOR increments only for a breaking change to the serialized shape.
A reader rejects a trace whose MAJOR is greater than the version it supports
(
schema_versionnewer than this build →422/TraceValidationError). - MINOR increments for backward-compatible additions. Older readers keep working because unknown fields are ignored (see below).
Current version: 1.1.
1.1 added the optional event field token_provenance (see below). It is a
backward-compatible addition: 1.0 traces omit it and stay readable.
Trace timing¶
The optional elapsed_ms field is either null or a finite, nonnegative JSON
number. Boolean values, numeric strings, collections, and numbers that overflow
the supported floating-point range are rejected with TraceValidationError
before conversion or storage. HTTP ingestion returns 422 with the same field
and reason. Missing or null elapsed time continues to use timing fallbacks.
Event fields¶
Each event object has these fields. Required fields must be present and non-null.
| Field | Type | Rule |
|---|---|---|
event_id |
string | required, non-empty, unique within the trace |
run_id |
string | required, must equal the trace's run_id |
event_type |
string | required, non-empty |
name |
string | required, non-empty |
started_at / ended_at |
string | required, non-empty (ISO-8601) |
duration_ms |
number | required, finite, ≥ 0 |
input_tokens / output_tokens |
integer | ≥ 0 |
token_provenance |
string | null | optional; where the token counts came from (see below) |
status |
string | one of ok, error |
parent_id, model, input_text, output_text, error |
string | null | optional |
metadata |
object | JSON object |
Validation failures raise agentloop.schema.TraceValidationError, which carries
the offending field path (for example events[2].duration_ms) and a reason.
Core code stays framework-free; the HTTP server maps this error to a 422
response {"detail": {"field": …, "reason": …}}.
Operation semantics are carried in metadata.operation_kind, without changing
the serialized event fields or schema version. See Operation kinds
for the taxonomy, legacy defaults, unknown-label policy, and OTLP mapping.
Token provenance¶
input_tokens / output_tokens carry both provider-reported usage and, when a
caller supplies text but no counts, a whitespace word-count approximation.
The two are not interchangeable, so each model call records where its numbers
came from in token_provenance:
| Value | Meaning | Exact? |
|---|---|---|
provider |
the provider reported usage (e.g. an OpenAI usage object) |
yes |
tokenizer |
counted with a real tokenizer for the target model | yes |
user_supplied |
explicit counts passed by the calling application | yes |
external_reported |
imported counts without independently verified provider accounting | no |
estimated_words |
the len(text.split()) fallback; an approximation |
no |
unavailable |
no counts were available and none could be estimated | no |
A seventh value, unspecified, is a read result only — it is what a reader
reports for an event that has no token_provenance (a 1.0 trace) or one whose
value this build does not recognize. Producers never write it.
Aggregating those per-event values over a trace's model calls gives the
token_status reported in report()["token_status"] and in
cost_breakdown.token_status: one of exact, partial, estimated,
unavailable, unspecified, empty, or external_reported. Only treat token totals — and any cost
calculated from them — as a measurement when token_status is exact or
empty. See agentloop/tokens.py.
Compatibility path for 1.0 traces¶
A trace written before 1.1 has no provenance to read, so AgentLoop cannot tell
whether its counts were provider usage or word estimates. Such traces:
- stay readable, unchanged, with no migration step;
- report
token_statusasunspecified, so nothing presents them as exact; but - still evaluate cost gates, because turning every configured cost gate
indeterminate on upgrade would break existing CI for traces that may well have
carried real usage. A trace that positively declares
estimated_wordsdoes not gate on cost — there the producer told us the number is a proxy.
Re-record a trace with the current version to get an exact classification.
Unknown provenance values¶
Unlike status, token_provenance is validated only as "a string or null", not
as a closed enum. A value from a newer MINOR version must not make a trace
unreadable, so an unrecognized value is preserved verbatim and graded
unspecified — never silently read as exact. Producers are held to the closed
set: passing an undefined value to the tracer raises TokenProvenanceError.
Compatibility policy¶
Backward compatibility (reading older traces)¶
Traces written before this schema existed (the 0.4 era) have no
schema_version. Readers treat a missing version as compatible and load them
unchanged — there is no migration step. This is covered by round-trip tests.
Forward compatibility (unknown fields)¶
Policy: ignore. Unknown top-level trace fields and unknown event fields from a newer MINOR version are dropped on read, never rejected. This lets a newer producer add fields without breaking an older reader.
If you need custom data to survive a round trip, put it in metadata — that
object is always preserved end to end. Transport bookkeeping keys that AgentLoop
itself sets during OTLP interop (for example otel_span_id) are reserved and are
not re-exported as user metadata.
OTLP interop¶
See telemetry conformance for pinned GenAI, OpenInference, and MCP fixtures, supported fields, evaluation logs, and known gaps.
The OTLP adapter (agentloop/otel.py) exposes two import
entry points with an explicit single-vs-batch contract:
trace_from_otel(payload, name=None) -> AgentTrace— for a payload that describes exactly one trace. If the payload contains spans from more than onetraceId(a batch), it raisesTraceValidationErrorrather than collapsing the traces. An empty payload yields an empty trace.traces_from_otel(payload, name=None) -> list[AgentTrace]— for batches. Spans are grouped bytraceId(in first-seen order, regardless of how they are interleaved) into one trace each. Spans without a trace id are grouped into a single trace. Parent links are resolved within a trace only, so a repeated span id in two traces never links across the boundary.
Both accept the standard OTLP shape (resourceSpans → scopeSpans → spans), a
{"spans": [...]} object, or a raw list of span dicts.
Identity & metadata round trips¶
trace_to_otel() writes the native trace name and run id as resource
attributes (agentloop.trace.name, agentloop.run_id) and the native
event/parent ids as span attributes (agentloop.native_event_id,
agentloop.native_parent_id). On import, trace_from_otel() reads these back to
restore AgentLoop-native identity, so a native trace preserves its name, run id,
event ids, parent structure, token provenance, and event metadata across one
and repeated OTLP round trips. Provenance rides as the span attribute
agentloop.token_provenance; on a third-party span that has none, AgentLoop
classifies from what the span actually carried — standard gen_ai/llm usage
attributes come from provider usage and read as provider, and a span with no
usage attributes reads as unavailable rather than a measured zero. Event metadata is exported under the agentloop.metadata. namespace
and decoded exactly once on import. Third-party resource/span attributes on a
non-AgentLoop OTLP payload are preserved as event metadata without collision.
Harness decision metadata¶
Enabled Python harnesses use the reserved trace metadata key agentloop.harness
for the independent decision-evidence schema 1.1, with 1.0
read compatibility. Native
trace schema remains 1.1; existing traces and application-owned metadata such as
harness keep their original meaning. The new namespace contains decision IDs,
historical policy declarations, outcome/dispatch evidence, timing, and explicit
retry/conflict references. Raw configuration capture is opt-in.
Native JSON and AgentLoop OTLP resource metadata preserve this namespace, including traces without execution spans. Unknown evidence versions remain opaque metadata; the evidence reader reports them as unsupported, and HTML omits their raw content. A logged control decision is not a verified intervention outcome or a security audit. See harness decision evidence for privacy and linkage.