Complete
AgentTraceDAG
A time-travel debugger for LLM agents.
- Role
- Sole author
- Stack
- Python · SQLite
- Code
- Repository →
Step-level
context, payload and token replay
SQLite
single-file, portable run archive
DAG
branching runs, not flat logs
How it works
- 01 Instrument wrap the agent loop
- 02 Record step context, tool payload, tokens
- 03 Diff against parent store deltas, not copies
- 04 Rebuild on replay exact context per node
- 05 Step / branch walk forward and back
Runs are graphs, so the debugger is a graph walk.
Recorded per step
Everything needed to reconstruct the moment, without storing the moment twice.
The problem
When an agent run goes wrong, the logs tell you the final answer was bad. They do not tell you which tool payload poisoned the context, at which step, or what the model could actually see at that moment. Debugging degrades into re-running and hoping the failure repeats.
The approach
Record every step of a run into a SQLite-backed DAG — context window, tool call and payload, token usage, edges between steps — then replay it. Stepping forward and backward through the run shows the exact context the model held at each node, including the branches that were abandoned.
What broke
Naive recording ballooned: storing the full context per step duplicates almost everything as windows grow. Keeping diffs against the parent node and reconstructing on replay made long runs cheap to archive, at the cost of replay code that must rebuild state exactly — which is where most of the tests ended up.
What worked
A failed run became a walk through a graph instead of an archaeology exercise. The same recording gives per-step token accounting, which turns out to be the fastest way to find a prompt that is quietly costing money.