agent-replay (Python)
Record & replay LLM API calls for deterministic agent tests.
agent-replay captures the HTTP traffic your agent makes to LLM providers
(Anthropic, OpenAI, …) into a human-readable JSONL "cassette", then plays it
back on subsequent runs so your tests are fast, offline, and deterministic —
while still flagging when a prompt has drifted away from what was recorded.
Install
pip install agent-replay-py
The install name is agent-replay-py; the import name is agentreplay
(there is an unrelated agentreplay project on PyPI, so we distinguish the
distribution name).
Optional extras:
pip install "agent-replay-py[pytest]" # pytest fixture & marker
Quick start
import agentreplay as ar
with ar.cassette("tests/cassettes/hello.jsonl", mode="auto") as c:
client = c.httpx_client() # a preconfigured httpx.Client
r = client.post(
"https://api.anthropic.com/v1/messages",
json={"model": "claude-3", "messages": [{"role": "user", "content": "hi"}]},
)
print(r.json())
- First run: the cassette file doesn't exist yet → records the real response.
- Later runs: the file exists → serves the recorded response, no network.
modeaccepts"record" | "replay" | "auto" | "passthrough", and can be overridden globally viaAGENTREPLAY_MODE.
Async is the same shape:
async with ar.cassette("tests/cassettes/hello.jsonl") as c:
async with c.httpx_async_client() as client:
r = await client.post(...)
pytest
agent-replay ships a pytest plugin. Cassettes are auto-named from the test
node id and stored under tests/cassettes/.
import pytest
@pytest.mark.agentreplay(mode="auto")
def test_agent(agentreplay):
client = agentreplay.httpx_client()
...
CLI
agentreplay inspect tests/cassettes/hello.jsonl # header + summary
agentreplay show tests/cassettes/hello.jsonl 0 # pretty-print seq 0
agentreplay verify tests/cassettes/hello.jsonl # re-check fingerprints
Divergence
When the request your code sends no longer matches what was recorded (a
prompt changed, a tool schema was edited, …), agent-replay produces a
structured diff (ar.Report) instead of silently returning stale data. The
divergence policy ("warn" | "error") controls whether it raises.
License
MIT — see LICENSE.
The TypeScript sibling of this package lives at
@retr0hxx/agent-replay.
Metadata
Release files for agent-replay-py 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_replay_py-0.1.0.tar.gz | 21.0 kB | Without provenance | Details for agent_replay_py-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_replay_py-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agent_replay_py-0.1.0-py3-none-any.whl |
Total release size: 44.5 kB
Release files / agent_replay_py-0.1.0.tar.gz
| Download URL | agent_replay_py-0.1.0.tar.gz |
|---|---|
| Size | 21.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
af4eda26624ba32297da6e39b64867e9c8fef8c7057cb9085e367f28ecb1d021
|
|
BLAKE2b-256 checksum How to use checksums |
d14385ca3d0634945977b7c392a699ff5e56f67762573b9b531e57fb82a3ad21
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.9
|
Release files / agent_replay_py-0.1.0-py3-none-any.whl
| Download URL | agent_replay_py-0.1.0-py3-none-any.whl |
|---|---|
| Size | 23.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
542c1b2f0229aebb37db79896efa7105816486c0856fcf6d59efc1846dc07d4b
|
|
BLAKE2b-256 checksum How to use checksums |
d7484a5623d6fc3ce52165a89f24ddd55b0afbf56eb22587cd29609c1fa441df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.9
|
Security for agent-replay-py 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.