A local replay tool for debugging broken AI agent loops
When an agent gets stuck in repeated tool calls and fails, a long JSON log in a cloud dashboard can be hard to use for real debugging. This approach records the , headers, , and time values from a run into a local trace file.
The command `replay-proxy record python agent.py` captures the run, and `replay-proxy replay trace.json` repeats the same path later with Wi-Fi turned off. That lets a developer step through the failure locally with pdb or VS Code instead of guessing from a huge log.
The tool works by patching Python networking pieces inside , and by taking control of time.time() and random.seed() while the program runs. It can handle normal async loops, but it breaks when the agent uses ProcessPoolExecutor for heavy work.
Key points
- The tool targets agent failures that are hard to debug from long JSON logs.
- It saves details, headers, , and time values into a local trace file.
- A recorded failure can be replayed offline so it follows the same path again.
- can inspect the replay with pdb or VS Code.
- It currently fails when ProcessPoolExecutor is used for heavy .