A flat log can tell you that five things happened. It often cannot tell you which operation caused the next one, which failure triggered a fallback, or whether three tool calls were children of one planning step or unrelated work.
That distinction matters for AI agents because the path is part of the behavior.
I maintain AgentInspect, an open-source TypeScript toolkit for inspecting agent executions locally. This article explains why I chose execution trees as the primary debugging model, using synthetic fixtures verified against agent-inspect@6.17.4.
This is enough to reconstruct a simple story, but the reconstruction is happening in your head. Add nested agents, parallel tools, reused operation names, and interleaved application logs, and timestamps stop being a reliable picture of causality.
The tree does not replace raw event data. It is a projection of that data for the question developers usually ask first: What path did this run take?
AgentInspect provides wrappers for a run and for named steps. Here is a deliberately small example:
This is manual instrumentation. It does not claim that a wrapper can automatically discover every framework-internal operation. The purpose is to record the boundaries you care about: the run, its planning step, the two sibling tool calls, and the final model-facing step.
Those two spaces are not decoration. They tell us that inner belongs to middle, which belongs to outer. If inner fails, we know which higher-level operation owned it. With flat logs, matching IDs or surrounding timestamps would be required to infer the same structure.
Nesting is especially useful when one agent delegates to another, a tool performs several sub-operations, or a retrieval step owns both a query rewrite and a vector search. Fallbacks expose recovery behavior
The final run may still be successful. If we looked only at the answer, the failed primary search could disappear from the debugging story. The tree preserves both facts: the primary path failed; the recovery path completed.
That distinction can change the engineering decision. A successful answer produced by a fallback may be acceptable, but a sudden rise in fallback use could still indicate a degraded dependency or an expensive routing change. Repeated siblings expose retries
A final success status would hide the cost of reaching success. The repeated tool name makes the retry sequence visible. It also gives a deterministic check something concrete to evaluate: for example, whether fetch-inventory exceeded an allowed call count.
The tree alone does not tell us whether the retry policy was correct. It gives us evidence that the policy was exercised. Parallel siblings expose concurrency
The durations are not meant to be added. These steps are siblings, and may overlap. That protects us from a common timeline mistake: assuming each timestamped operation waited for the previous one.
The tree does not prove that concurrency was optimally implemented, but it accurately preserves the structural relationship needed to investigate it.
It is tempting to turn a readable tree into the only stored artifact. I avoided that because a human-readable view necessarily compresses information.
The underlying trace may include identifiers, timestamps, status, inputs or outputs (subject to capture policy), observations, and metadata. Different questions need different projections:
An execution tree is the fastest entry point, not a substitute for checks or analysis.