Deterministic Replay for AI Agent Systems
06:00 · July 21, 2026 · arXiv cs.AI RSS
AI agent systems that couple large language models (LLMs) with external tools and APIs are inherently non-deterministic: LLM sampling variance, external API state, CDN infrastructure headers, and execution-environment noise collectively prevent any prior agent run from being faithfully re-executed. Existing observability platforms capture execution logs but cannot reproduce a run in isolation. 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, serialises them as structured execution traces, and replays them in a strictly isolated environment with zero outbound network access. We formalise the agent execution model, define the request-key matching function K(s), and prove the determinism invariant. We introduce a noise-aware diff algorithm classifying HTTP header divergence into signal and noise tiers. Empirical evaluation across five workloads (n = 250 replay instances) demonstrates replay fidelity F = 1.0 and a median per-step latency reduction of 98.3%. agrepl is implemented in Go, ships as a single static binary, and is released under the MIT licence. Keywords: AI agents, deterministic replay, LLM debugging, reproducibility, MITM proxy, execution tracing, record/replay systems.
Summary
AI agent systems that combine large language models with external tools and APIs face inherent non-determinism. Sampling variance in the model, changing states in remote services, variable headers from content-delivery networks, and differences in the local runtime all make exact re-execution of a prior run practically impossible. Conventional observability tools record execution traces yet leave developers without a way to reproduce the same sequence in a controlled setting.
agrepl addresses this gap with a command-line framework that records every outbound interaction through a man-in-the-middle proxy operating at the transport layer. The captured exchanges are stored as structured traces that can later be replayed inside an isolated environment that blocks all real network traffic. By substituting recorded responses for live calls, the system eliminates external sources of variance while preserving the original control flow of the agent.
The authors formalise the underlying execution model and introduce a request-key matching function K(s) that pairs each outgoing call with its recorded counterpart. They prove that, under the defined matching rules, replay satisfies a determinism invariant. A complementary noise-aware diff algorithm partitions HTTP header differences into signal and noise categories, allowing engineers to focus on meaningful divergences rather than transient infrastructure artefacts.
Empirical tests across five representative workloads and 250 replay instances report perfect fidelity (F = 1.0) together with a 98.3 % reduction in median per-step latency. The implementation is written in Go, distributed as a single static binary, and released under the MIT licence, enabling direct integration into existing development and debugging workflows.
Why it matters
Directly actionable for Dutch AI researchers and advanced practitioners working on agent systems, offering high technical depth, reproducibility resources, and alignment with EU emphasis on transparent, reliable AI.
