An agent trace is usually written as a sequence of events because append-only data is simple to produce:
span_started
span_started
span_ended
span_started
span_ended
span_ended
Developers do not want to debug that sequence directly. They want to see the causal structure:
research_agent
├─ search_web
├─ query_database
├─ call_finance_api
│ ├─ attempt_1 timeout
│ └─ attempt_2 ok
└─ summarize_results
The event stream is optimized for writing. The execution tree is optimized for understanding. Building a reliable tree requires more than sorting by timestamp: events may arrive out of order, siblings may run concurrently, spans may be incomplete, and retries may fail while the parent operation still succeeds.
The Minimum Event Contract
Every event needs stable trace and span identity. Start events establish parentage; end events establish outcome and duration.
type SpanKind = 'run' | 'model' | 'tool' | 'retrieva
Discussion
Your thoughts matter!
Your input is valuable—be the first to share it!