Turn Agent Tool Calls Into Run Receipts
The fastest way to debug a failing agent is not a better prompt; it's a better record of what the tools changed. Chat logs capture what the model said. A run receipt captures what the workspace did. Keep the second, and the first becomes optional. Most agent debugging starts too late. The run fails, the transcript scrolls away, and you're left reconstructing history from git blame and guesswork.…
Debugging a failing agent often requires more than improving prompts; it demands an improved record of the tools' actions. While chat logs show what the model said, run receipts record what the workspace did. Recording run receipts at each tool call prevents the loss of valuable transcripts when the run fails. Observability for an agent run should be written down immediately after each tool call using a wrapper that doesn't depend on the model that produced the call.
This concept is similar to a courier's tracking system, which records the status of each stop but doesn't reveal the driver or location of each stop. An agent that emits a JSON line per tool call serves as this courier, providing a simple and auditable way to track the agent's actions. To implement this, the minimal version requires three components: a stable run ID, a git workspace, and a wrapper around the tool-call boundary.
The provided example code demonstrates how to create a receipt file for each tool call using Node.js. The receipt file includes fields such as the run ID, the current git commit hash, the number of files changed, the number of added and deleted files since the last snapshot, and a duration measurement for each step. By using this approach, developers can efficiently debug failing agents and maintain a clear audit trail of the agent's actions.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
