Inspect what your agent actually did. Find out why it failed. Prove the fix works.
Loupe is a local-first, open-source debugging platform for AI agents — built for developers who ship agents in production and need to understand, replay, and verify agent behavior the way rr works for C programs or Chrome DevTools works for web apps.
AI agents fail in ways traditional software doesn't. The root cause is rarely the model — it's the system around it: bad tool inputs, unexpected state, missed edge cases, cascading errors across multi-step reasoning. Existing tools give you logs. Loupe gives you causality.
- 88% of agent failures are caused by the system, not the model.
- Teams spend 40% of sprint time investigating agent failures.
- Zero open-source tools combine recording, replay, causal tracing, and CI verification in one platform.
Loupe changes that.
pip install loupe-agentThe PyPI package is loupe-agent; the Python import package and CLI remain loupe.
from loupe import record
with record("support-agent") as trace, trace.span(
"tool.lookup", kind="tool", inputs={"query": "refund policy"}
) as span:
span.set_outputs({"result": "30-day refund window"})Traces are written to .loupe/traces.db automatically.
loupe list # list all recorded traces
loupe inspect <trace-id> # inspect span tree, inputs, outputs, errors
loupe graph <trace-id> # render causal graph as SVG
loupe evaluate <trace-id> # run deterministic evaluationloupe init
loupe record-demo
loupe listDrop-in SDK captures every agent step: spans, events, inputs, outputs, errors, latency, and token counts. Zero code changes for LangChain integrations.
Record once, replay infinitely. Stored outputs and mock patches ensure byte-identical results every time — no more "works on my machine" failures.
Automatic dependency graphs show which span influenced downstream behavior. Blame assignment ranks likely failure causes: bad input, wrong tool, bad prompt, or model hallucination.
Deterministic evaluation gates catch agent behavior regressions before they ship. Run evaluations in your existing CI pipeline.
SQLite storage by default — your traces never leave your machine. Export summaries to Arrow/Parquet for downstream analysis.
Serve traces over FastAPI for integration with web-based trace explorers and dashboards.
Agent Code
│
▼
┌─────────────────┐ ┌──────────────────┐
│ Loupe SDK │────▶│ .loupe/traces.db │
│ (record spans) │ │ (SQLite) │
└─────────────────┘ └────────┬───────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
loupe inspect loupe graph loupe evaluate
(CLI detail) (causal DAG) (deterministic eval)
│ │ │
└────────────┴────────────┘
│
FastAPI Server (optional)
│
SvelteKit Dashboard (optional)
| Framework | Status | Integration |
|---|---|---|
| LangChain | Scaffolded | Callback handler |
| CrewAI | Planned | Event listener adapter |
| AutoGen / AG2 | Planned | Message hook interceptor |
| LangGraph | Planned | Node middleware |
| Raw OpenTelemetry | Planned | Span exporter bridge |
# Clone and install
git clone https://github.com/itseasy21/loupe.git
cd loupe
python -m pip install -e '.[dev]'
# Run quality checks
python -m ruff check .
python -m mypy loupe
python -m pytest
# Or use pre-commit hooks (recommended)
python -m pip install pre-commit
python -m pre-commit install
python -m pre-commit run --all-files# Start the API server
cd loupe && uvicorn loupe.api.server:app --reload --port 8000
# In another terminal, start the frontend
cd frontend && npm install && npm run devContributions are welcome. See CONTRIBUTING.md for setup instructions, coding standards, and the PR process.
- Bugs & issues: https://github.com/itseasy21/loupe/issues
- Discussions: https://github.com/itseasy21/loupe/discussions
Loupe is open-source under the Apache 2.0 License.