The post-mortem debugger for AI agents. When your agent fails silently — AgentAutopsy tells you exactly why.
Lifecycle
Install → Watch → Fail → Trace → Replay → Fix
│ │ │ │ │ │
pip watch() silent SQLite rewind auto-fix
install failure log + fork + cache
| Stage | What happens |
|---|---|
| Install | pip install agentautopsy — no cloud account, no config file |
| Watch | agentautopsy.watch() intercepts LLM, HTTP, MCP, and tool calls |
| Fail | Agent errors or returns bad output; run is marked in local SQLite |
| Trace | Full event timeline: prompts, tools, schemas, tokens, timestamps |
| Replay | Rewind to any step, fork with new input, diff original vs replay |
| Fix | Root-cause report, AI chat on trace, verified fix cached for next run |
Commands
| What you're doing | Command | Key principle |
|---|---|---|
| Zero config setup | agentautopsy.watch() |
One import catches everything |
| View trace UI | agentautopsy ui |
Visual timeline of every step |
| Replay a failure | agentautopsy replay --run-id <id> --from-step <n> |
Rewind to exact failure point |
| Detect schema drift | SchemaDriftDetector().watch() |
Catch API changes before production |
| Trace MCP servers | MCPAutopsy().watch_mcp_server() |
Every MCP call recorded |
| Fork and fix | DVRReplay().fork(run_id, at_step=3) |
Branch from any step |
| Generate tests from failures | agentautopsy generate-evals |
Never fix the same bug twice |
| Detect runaway loops | agentautopsy loops |
Never get a surprise $400 bill again |
| Monitor context usage | agentautopsy context --run-id <id> |
See exactly which step is eating your context |
Quick Start
pip install agentautopsy
import agentautopsy
agentautopsy.watch()
# your existing agent code — nothing else changes
Features
| Feature | What It Does | Use When |
|---|---|---|
| MCP Post-Mortem Tracing | Traces every MCP server call, shows bad data source | Using Claude Code, Cursor, any MCP client |
| Schema Drift Detector | Detects renamed/removed/added fields automatically | After any API or tool upgrade |
| DVR Fork and Replay | Rewind, replay, fork from any step | Debugging production failures |
| Swarm Tracing | Causality tracing across 50+ agents | Multi-agent workflows |
| AI Chat on Trace | Ask questions about your failure | When root cause is unclear |
| Prompt Diffing | Compare runs side by side | Optimizing agent behavior |
| Contract Checkpointing | Enforces Pydantic schemas and checkpoints valid states | Preventing late-stage failures caused by early bad data |
| Automatic Eval Generation | Generates pytest test cases from every failure automatically | When you want to make sure the same failure never happens again |
| Runaway Loop Detector | Detects repeated tool calls and kills agent when cost exceeds threshold | When you want to prevent $400 bills from runaway agents |
| Context Window Monitor | Tracks context usage per step, warns at 70% and 90%, detects silent truncation | When your agent starts giving garbage answers near context limit |
Framework Support
Works with: LangChain, LangGraph, CrewAI, AutoGen, LlamaIndex, OpenAI, Anthropic, MCP
Module Quick Start
Basic
import agentautopsy
agentautopsy.watch()
MCP
from agentautopsy import MCPAutopsy
MCPAutopsy().watch_mcp_server("my-mcp-server")
Schema Drift
from agentautopsy import SchemaDriftDetector
SchemaDriftDetector().watch()
DVR Replay
from agentautopsy import DVRReplay
dvr = DVRReplay()
dvr.replay(run_id, from_step=3)
dvr.fork(run_id, at_step=3, new_input={"query": "fixed prompt"})
Auto Eval Generation
from agentautopsy import EvalGenerator
gen = EvalGenerator()
gen.generate_all() # generates tests from all recorded failures
Loop Detector
from agentautopsy import LoopDetector
detector = LoopDetector(max_cost_usd=1.00, max_iterations=20)
detector.watch()
Context Monitor
from agentautopsy import ContextMonitor
monitor = ContextMonitor()
monitor.watch()
Contract Checkpointing
from agentautopsy import ContractCheckpointer
from pydantic import BaseModel
class OutputSchema(BaseModel):
__rules_version__ = "1.0" # Optional: bump to force cache invalidation on external dependency drift
summary: str
checkpointer = ContractCheckpointer(run_id)
# Fails immediately if invalid, otherwise saves state to SQLite for resuming.
# Automatically normalizes and hashes the AST (Abstract Syntax Tree) of the validator, global constants, and helper functions to detect logic drift without false positives!
validated = checkpointer.enforce("step_1", raw_output, OutputSchema)
Contributing
Fork the repo, open a PR with tests. See CONTRIBUTING.md for setup and CI commands.
License
MIT — see LICENSE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
agentautopsy-2.4.0.tar.gz
(109.5 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
agentautopsy-2.4.0-py3-none-any.whl
(104.5 kB
view details)
File details
Details for the file agentautopsy-2.4.0.tar.gz.
File metadata
- Download URL: agentautopsy-2.4.0.tar.gz
- Upload date:
- Size: 109.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
26408b85a964562c20a461e85bb2c7f15f587501507b85f36436558fcfe19d02
|
|
| MD5 |
9ac6cedd56a90b3a95519b1d9f43f8cc
|
|
| BLAKE2b-256 |
13a05f61578f2d08e23d8af48f6b08d05f1e89cf791a5050528e753bf5d1f9c1
|
File details
Details for the file agentautopsy-2.4.0-py3-none-any.whl.
File metadata
- Download URL: agentautopsy-2.4.0-py3-none-any.whl
- Upload date:
- Size: 104.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
242ce1cc484a9c610861107373c3efb92d243f514899d7943ec52e817172df55
|
|
| MD5 |
61a717e44afef5e09a5268e8127379a3
|
|
| BLAKE2b-256 |
7b2f14fb66fa70883c96afd33c17879544cf45d823452d390f4662e30fe0b095
|
