In AI agent systems, the integration of large language models (LLMs) with external tools and APIs inherently leads to non-determinism. Variances in LLM sampling, external API states, CDN infrastructure headers, and execution environment noise collectively hinder the faithful re-execution of any prior agent run. Existing observability platforms can capture execution logs but fail to reproduce a run in isolation. To address this, we present agrepl, a developer-first CLI framework for deterministic replay of agent executions.
agrepl intercepts all external interactions at the transport layer via a man-in-the-middle (MITM) proxy, serializes them as structured execution traces, and replays them in a strictly isolated environment with zero outbound network access. We formalize the agent execution model, define the request-key matching function K(s), and prove the determinism invariant. Additionally, we introduce a noise-aware diff algorithm that classifies HTTP header divergence into signal and noise tiers.
Empirical evaluation across five workloads (n = 250 replay instances) demonstrates a replay fidelity F = 1.0, with a median per-step latency reduction of 98.3%. agrepl is implemented in Go, shipped as a single static binary, and released under the MIT license.
Blogger's Review: This research provides a robust tool for debugging and reproducibility in AI agents, employing MITM proxy technology to achieve deterministic replay in an isolated environment. By reducing latency and ensuring replay fidelity, agrepl offers developers a more efficient debugging approach, advancing the reliability of AI applications.