Agent Runs Are Black Boxes: A Trace-First Debug Loop
As agents take on more coding work, the developer's job shifts from writing to reviewing. Reviewing without a trace is guessing. When an agent misbehaves, the instinct is to edit the prompt — but the prompt is the wrong artifact. The run is the artifact: the ordered list of tool calls, diffs, and token spends that actually happened. Trace it before you tune it.
An agent is not a function. A function maps an input to an output; an agent maps a task to a sequence of side effects, and each side effect changes the next decision. Rerun the same prompt and you may get a different failure. That is why "it worked in my terminal" is not a debugging strategy, and why screenshots do not help: the interesting state is spread across ten steps, not one answer.
Debugging an agent without a trace is like debugging a network outage with ping alone. You know the packet left. You do not know where it died.
Here is a minimal, reusable trace harness. It writes one JSON event per line to an append-only JSONL file. Three event types matter: model calls, tool calls, and tool results — plus a diff snapshot after every tool execution. A preflight harness tells you whether the agent can start; this trace tells you what it did after. This is a minimal harness, not a library; adapt attribute names to your SDK.
