Agent Auditor
Find out why your AI agent fails, and prove the fix works before you ship it.
Agent Auditor is an open-source reliability layer for AI agents. It records every agent run, scores it, explains why failures happen, turns real failures into regression tests, and only lets a new version go live after a canary check and a human approval. Everything lands in an audit log.
Status: alpha (0.12). All planned phases are written and tested: tracing, evals, drift, failure-to-test, root causes, canary, release gate, change attribution and verified fixes, plus a plain-language dashboard and a working demo agent. It has been used on one developer's machine, not in production. See Known limitations.
Why this exists
Tracing tools show you what an agent did. When it breaks in production you still have to work out why, write the test by hand, change something, and hope the change did not break something else. Agent Auditor closes that loop:
run -> score -> root cause -> regression test -> proposed fix -> replay the tests -> canary -> approved release -> rollback
| Step | What you get |
|---|---|
| Trace | Every run with its steps (model calls, tools, retrieval) from a small Python SDK |
| Evaluate | Built-in checks that need no API key (errors, latency, empty answers, grounding), plus your own judge |
| Explain | A root-cause label per failure (rate limit, tool error, bad retrieval, slow run...) and which change likely caused it |
| Remember | One click turns a failed run into a regression test that is replayed against every new version |
| Compare | Drift detection and a canary that rolls back a version that is measurably worse |
| Ship safely | Release gate with approvals (you cannot approve your own), rollback, and a full audit trail |
How it fits together
flowchart LR
A[Your agent<br/>+ Python SDK] -->|runs and steps| B[Auditor API<br/>FastAPI + SQL]
B --> C[Evals<br/>built-in + your judge]
C --> D[Root causes<br/>+ change attribution]
D --> E[Regression tests<br/>from real failures]
E --> F[Fix candidates<br/>replayed on the tests]
F --> G[Canary<br/>vs the live version]
G --> H{Release gate<br/>approvals}
H -->|promote| I[Active version]
H -->|rollback| I
B --> J[(Audit log)]
B --> K[Dashboard<br/>15 pages]
Try it in 5 minutes
Needs Python 3.11 or newer. The core runs offline with no API key. Keys are only needed for the optional chat demo and AI helper.
git clone https://github.com/ArathiS1/agent-auditor
cd agent-auditor
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
uvicorn agent_auditor.api.main:app # API and dashboard on http://127.0.0.1:8000
In a second terminal, fill it with demo data and open http://127.0.0.1:8000/dashboard:
python examples/release_demo.py
Windows, one command: powershell -ExecutionPolicy Bypass -File .\run-all.ps1 starts the Auditor and the chat app
together, connected, and opens the dashboard. Add -Check to run a 23-point self-check afterwards.
Docker (API, worker, PostgreSQL): cp .env.example .env, set the two secrets, docker compose up --build.
See docs/deployment.md.
Use it with your own agent
from agent_auditor.sdk import Auditor
auditor = Auditor("http://127.0.0.1:8000", agent="support-bot")
auditor.register_version("v1", prompt=PROMPT, config={"top_k": 4})
@auditor.observe(kind="retrieval")
def kb_search(q): ...
@auditor.observe_run()
def answer(question): ...
Plain Python and LangGraph/LangChain are supported. See examples/quickstart_plain.py and examples/langgraph_demo.py.
The dashboard
Open /dashboard. Fifteen pages, grouped by what you are trying to do:
| Group | Pages |
|---|---|
| Watch | Overview (health verdict, one tick per run), Failures, Runs |
| Understand | Quality, Root causes, Drift |
| Improve | Versions, Regression tests, Fixes, Benchmark, Gap analysis |
| Ship safely | Canary, Releases |
| Govern | Audit log, Setup |
Every chart has a table view, and "Ask for help" answers questions from beginner to advanced (it works without a key from a built-in guide, and uses an AI provider when one is configured).
Auditor Chat: a real agent to watch
chatbot/ is a ChatGPT-style app that runs on your machine and reports every turn to Agent Auditor, so you always
have a real agent to inspect. It streams answers, remembers conversations, reads files and images, searches the web,
runs deep research, and compares models side by side.
- Many providers: Gemini, Groq, OpenRouter, Mistral, Cerebras, DeepSeek, xAI, Perplexity, OpenAI, Claude, Ollama,
and any OpenAI-compatible service you describe in
.env(NAME_API_KEY,NAME_BASE_URL,NAME_MODEL). - Auto-routing: the chat remembers which models are slow or rate limited and tries healthy, quick ones first
(
CHAT_AUTOROUTE=offto disable).GET /api/healthshows what it has learned. - Key doctor:
python chatbot/check_keys.pysays plainly whether each key works, is out of credit, or is busy.
Details: chatbot/README.md.
What it found on a real agent
Running the chat app as a live agent for a few days, the Overview reported most runs as problems. The cause was not a bug in the code: slow free or reasoning models tripped the latency check, and free tiers returned rate limits. That finding led directly to the auto-routing above. The point of the tool is that it showed this with evidence, per version and per cause, instead of leaving it as a feeling that "the bot is flaky".
How well does it work?
validation/ tests the tool against a support bot whose faults are planted, so the right answer is known.
On the included sample run:
- 3 of 5 planted faults were rolled back by the canary every time.
- Half-missing search results were caught 3 times in 5.
- Out-of-date facts were never caught. The built-in checks look at symptoms, not facts.
Run it yourself: python validation/run_validation.py --dry-run. Report and method: validation/README.md.
Design choices
- Fixes are proposals, not automatic edits. Rule-based candidates come from the root-cause report. A person registers one, the regression suite replays against it, a canary compares it, and a different person approves the release. Many failures (slow runs, rate limits) are infrastructure problems that no prompt change fixes.
- Cheap checks first. Built-in scorers need no API key, so the system works offline and costs nothing to run.
- Plain HTML dashboard. No build step and no CDN, served by the API itself.
A failure, start to finish
What the loop looks like on a real incident (numbers are illustrative):
- Overview turns red: "31 of 52 runs had problems."
- Root causes says why: slow run (25 runs), rate limit (14 runs), tool error (3 runs), and in which version it began.
- Failures lists each run. One click turns a bad run into a regression test.
- Fixes proposes small candidates. Each is registered as a separate, inactive version and replayed on every regression test. Only candidates that pass are recommended.
- Canary sends a slice of live traffic to the candidate and compares pass rate, latency and causes with the live version.
- Releases: a different person approves, you promote, and if it goes wrong you roll back with a written reason. Every step, including refusals, is in the audit log.
What is built
| Area | Contents | State |
|---|---|---|
| Core | Data model, FastAPI ingestion, versioned prompts and configs, audit events, Python SDK, LangGraph adapter | done |
| Evals | 7 built-in scorers, your own judge, version-to-version regression verdicts | done |
| Drift | Numeric, rate and term-mix signals with significance tests | done |
| Failure to test | Failed runs become deduplicated regression cases; replay against any version | done |
| Root causes | 11 cause types with sub-causes, suspect documents, change attribution | done |
| Canary and releases | Five checks, approval gate, rollback, audit trail | done |
| Fixes | Rule-based and optional AI candidates, verified on the regression suite | done, human-approved |
| Dashboard | 15 pages, plain HTML/CSS/JS, dark mode, built-in help chatbot | done |
| Auditor Chat | Multi-provider demo agent with auto-routing and key checks | done |
| Ops | Docker Compose, PostgreSQL, Alembic migrations, CI, background worker | done, PostgreSQL experimental |
Roadmap
Planned, in rough order. None of it exists yet.
- One-click "apply and verify" for fix candidates (register, replay and canary in one step)
- Real user authentication, so approvers are verified and not typed names
- Row locking for several operators on one release
- Fact-checking scorers that compare answers with source documents, not just symptoms
- A green PostgreSQL CI job, then promote PostgreSQL to supported
- Published package on PyPI
FAQ
Is this an observability tool like LangSmith or Langfuse? Partly. Those show what happened. Agent Auditor adds the steps after that: diagnosing the cause, writing the test, checking the fix and gating the release. It is much younger and smaller than they are, so pick it for the closed loop, not for scale.
Does it need an API key? No. Tracing, evals, root causes, drift, canary and releases run offline. Keys are only for the optional AI helper, AI-written fixes and the demo chat app.
Will it fix my agent automatically? No, by design. It proposes and proves fixes; a person approves the release. Many failures, such as slow runs and rate limits, come from the model or provider, and no prompt edit fixes them.
Can I use it with my own agent? Yes. Add the SDK decorators shown above to any Python agent.
Documentation
| docs/reference.md | Every phase in detail: evals, drift, failure-to-test, root causes, canary, releases, attribution |
| docs/architecture.md | How the pieces fit |
| docs/deployment.md | Docker, PostgreSQL, secrets |
| docs/case-study.md | A worked example: Agent Auditor watching its own chat agent, including what did not work |
Known limitations
- Alpha software. It has been run on one machine and is not yet proven under production load.
- Built-in scorers detect symptoms (errors, latency, empty answers), not whether an answer is factually right.
- Approver names are self-asserted behind one shared API key. Promotion marks a version active; it deploys nothing.
- Replay needs an agent that can be called again with the stored inputs. Agents that depend on live sessions or external state cannot be replayed faithfully.
- The AI helper can be wrong, so decisions stay with a person. With a provider configured, dashboard figures and your question are sent to that provider.
- The feature comparison in Gap analysis is kept by hand and may be out of date.
- The PostgreSQL CI job is experimental; SQLite is the tested backend.
- More in docs/reference.md.
Development
pip install -e ".[dev]"
ruff check src tests examples chatbot
pytest -q
Contributions are welcome: see CONTRIBUTING.md. Never commit .env or chat.db.
License
MIT. See LICENSE.
Metadata
Release files for agent-auditor 0.13.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_auditor-0.13.0.tar.gz | 248.3 kB | With provenance | Details for agent_auditor-0.13.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_auditor-0.13.0-py3-none-any.whl | Python 3 | none | any | Details for agent_auditor-0.13.0-py3-none-any.whl |
Total release size: 466.7 kB
Release files / agent_auditor-0.13.0.tar.gz
| Download URL | agent_auditor-0.13.0.tar.gz |
|---|---|
| Size | 248.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0c25007712f4e42b3bffe9603cd0bcd361095f6334864aac6906aac3d6707cbf
|
|
BLAKE2b-256 checksum How to use checksums |
fa120efb62bf8228e6a51755472fed6244bd59d928d2b31e9a6520fbb39dec4c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / agent_auditor-0.13.0-py3-none-any.whl
| Download URL | agent_auditor-0.13.0-py3-none-any.whl |
|---|---|
| Size | 218.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0d0351a98a03a9f9750c554f70ccb047c0ff0066c1cd3f36b1e8869877d2d376
|
|
BLAKE2b-256 checksum How to use checksums |
e94bf8093b1450ada874ec7dd60494dd964ae0f643d904dac2cedbb1d53efe30
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for agent-auditor 0.13.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agent_auditor-0.13.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA 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.