Skip to main content

Agent Auditor

Find out why your AI agent fails, and prove the fix works before you ship it.

status python license tests no api key needed

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=off to disable). GET /api/health shows what it has learned.
  • Key doctor: python chatbot/check_keys.py says 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):

  1. Overview turns red: "31 of 52 runs had problems."
  2. Root causes says why: slow run (25 runs), rate limit (14 runs), tool error (3 runs), and in which version it began.
  3. Failures lists each run. One click turns a bad run into a regression test.
  4. Fixes proposes small candidates. Each is registered as a separate, inactive version and replayed on every regression test. Only candidates that pass are recommended.
  5. Canary sends a slice of live traffic to the candidate and compares pass rate, latency and causes with the live version.
  6. 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)

Source distribution for agent-auditor 0.13.0
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)

Table of built distributions (wheels) for agent-auditor 0.13.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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.

Release history Release notifications | RSS feed

This release

0.13.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page