agentest: test what your AI agent actually did
agentest is an open-source testing tool for AI agents. It reads the OpenTelemetry traces your agent already recorded and runs executable checks that judge what the agent actually did, not only what it said: claimed success it did not earn, acted before verifying, followed a hidden instruction, called a tool it should not, or leaked personal data. It runs offline, with no API key, network or LLM judge, so the same traces always give the same verdicts. The PyPI package name is agentest-ai; the import and the CLI are agentest.
A real recorded run of a shopping agent in a mock shop (nothing was bought). Click the image to watch the 56-second video with voiceover.
Works with any framework that records OpenTelemetry GenAI traces. Native-log importers: LangGraph, OpenAI Agents SDK, AutoGen, smolagents and n8n. Worked pages: LangGraph, CrewAI, OpenAI Agents SDK. All examples.
Quickstart
Install from PyPI (Python 3.11+, no API key, no model). The package name is agentest-ai; the import and the agentest command stay agentest:
pip install agentest-ai
agentest --help
If the package is not on PyPI yet, install from GitHub: pip install git+https://github.com/srpadmanabhuni/agentest.
Then run a bundled example use case and read the markdown report.
- Install from PyPI, from GitHub, or from a clone of this repository.
- Run a bundled example use case — a shopping agent that said it added an item to the cart when the cart was empty (the clip above).
- Read the report — one markdown row naming the check, the verdict and the evidence.
From source, three lines (Python 3.11+, no API key, no model). This reproduces the run in the clip above and includes the examples folder:
git clone --depth 1 https://github.com/srpadmanabhuni/agentest.git && cd agentest
python3 -m venv .venv && . .venv/bin/activate && pip install -q -e .
agentest std run --agent a22 --ids T1-018 --format md
Expected: one row, T1-018 | fail | case2#0: effect although success signal failed. After pip install agentest-ai, the same command works without a clone because the bundled sample agents ship with the package (all install options). How to read pass / fail / n/a is in Reading the report.
If that run was useful, a ⭐ helps other people find agentest.
No install, in your browser: the Assurance Report Card (paste or upload a trace; three samples included) or Open in Colab (free CPU, no login, no model).
Catalogue: the Agentic AI Test Checklist 110, the per-test guide (T1–T7 and X), and the opt-in New tests NT-001–NT-030.
Contributing: CONTRIBUTING.md — start with a good first issue.
Tutorials
Six short walkthroughs in this repository. Each one runs from the same clone as the quickstart (about 5–10 minutes).
| # | Tutorial | Checks |
|---|---|---|
| 1 | Unauthorized tool calls | T5-001, T5-005 |
| 2 | Prompt injection | T4-001, T4-003, T4-007 |
| 3 | State drift across turns | T6-002, T6-003 |
| 4 | CI/CD with GitHub Actions | all 130, gated with --strict |
| 5 | Multi-agent handoffs | T3-001, T3-002, T3-007, T3-008, T3-010, T3-011 |
| 6 | Personal data and secret leaks | T5-004, T4-009, T6-011, T7-014 |
Index: docs/tutorials/README.md.
Agent Testing 101 on Substack (publication):
- Build a Tiny AI Agent and Test It with agentest
- Test AI Agents for Unauthorized Tool Calls in 5 Minutes
- Launch note: I'm launching agentest
Related article: 100 Days of Testing Agentic AI on Hashnode.
Where things live
This repository is the front door. The other public repos and Spaces are companions; start here, then follow the link you need.
| Resource | What it is for |
|---|---|
| agentest (this repository) | The runner: install it, run the checks, read the report, and contribute. Package name agentest-ai; import and CLI agentest. |
| agentest-starter | A template that runs agentest on a sample agent, then on your own recorded traces. |
| Reference agents | 132 practice agents with recorded runs, on Hugging Face. |
| Agentic AI Test Checklist 110 | The open catalogue of 110 test designs (objectives, pass/fail signals). |
| Assurance Report Card | Paste or upload a trace in the browser and see which checks fail; no install. |
| Checklist browser | Filter and export the 110 tests in the browser. |
| Reference-agents viewer | Read the recorded runs of the reference agents. |
Choose your path
| I am... | Start with |
|---|---|
| A developer (install, first run, CI, CLI and API, contributing) | Quickstart · Tutorials · Point it at your agent · CI gate · CLI and API reference · Contribute |
| A tester / QA (what each test checks, manual use, packs, priorities, reading verdicts) | Tester quickstart · Per-test guide, all 130 IDs · Plan by priority · Read a verdict · Use the checklist by hand |
| New to agent testing | Start here: what an agent test is, a three-step first run (about 10 seconds), how to read the result, and how to test your own agent. |
Launched 15 Nov 2026. Try it from source in under 3 minutes. Then take the challenge, or open a good first issue.
Contents: Quickstart · Tutorials · Where things live · Why agentest · 60-second first win · Your agent · Read a verdict · What it checks · Learn more · Roadmap · Contribute · Related · Author, citation, licence
Why agentest
agentest reads the traces your agent already recorded and tells you, check by check, what it did wrong: claimed success it did not earn, acted before verifying, followed an instruction hidden in a document, called a tool it should not, or leaked personal data. It needs no account, API key, network or LLM judge, so the same traces always give the same verdicts.
Who it is for
- Agent developers: catch broken tool calls, unearned "Done!" replies and prompt injection before your users do. It works from the traces your agent already records, so it fits any framework, and
--strictmakes it a one-line CI gate. - QA and testers: 130 ready-made executable checks with deterministic
pass/fail/n/averdicts and an evidence line each. No LLM judge, so no flaky scores. It reads OpenTelemetry GenAI traces, A2A AgentCards and MCP tool lists.
What makes it different (every point, with its source):
- One open suite of 130 executable checks spanning evals, security, privacy and responsible behaviour.
- Judges what your agent did (tool calls and results), not only what it said.
- Deterministic and offline: no LLM judge, API key or network.
- Open standards, no lock-in: reads OpenTelemetry GenAI, A2A AgentCard and MCP tool annotations from any framework, and never asks your agent to import it (No lock-in, agent-independence audit).
- Gates CI:
--strictexits 1 on anyfail; JUnit, SARIF, JSON, HTML, Markdown and CSV output.
Use it for a pre-release gate, regression checks after a prompt change, security review, or evaluating another team's agent. Limits, known false positives and coverage are in How it works. Not certification.
Your move: try the quickstart, take the challenge: can your agent pass these tests?; or open a good first issue.
60-second first win
A longer run, from the same clone as Quickstart. This runs agentest on a bundled sample agent that has seeded bugs and checks four things at once:
agentest std run --agents examples/agnostic_demo/agents --agent refill_bot_buggy \
--ids T1-018,T2-001,T4-003,T7-014 --format md
It prints a caught-bug report: one line of evidence per failed check.
A rendering of the real output, with a plain-English label added per check. The evidence text is verbatim (T2-001 shortened); the plain --format md output is a table of the same rows.
For contrast, the clean sibling agent passes everything it can be judged on: agentest std run --agents examples/agnostic_demo/agents --agent refill_bot prints refill_bot: 55 pass, 0 fail. The same before-and-after walkthrough is in the Colab above, or run python examples/colab_quickstart.py from the clone.
Now point it at your agent
# 1. Judge your agent's OpenTelemetry GenAI traces
agentest std run --otlp my_traces.otlp.jsonl
# 2. Optionally add its A2A AgentCard and MCP tools list for more checks
agentest std run --otlp my_traces.otlp.jsonl --card agent-card.json --tools tools.json
# 3. Gate CI (also json, sarif, html, md, csv)
agentest std run --otlp my_traces.otlp.jsonl --format junit --out agentest.xml --strict
No traces yet? Emit one with the standard library, import a native log, or use LangGraph (run python examples/langgraph_import/test_langgraph.py for an offline example). A check with no evidence in your trace says n/a, never a silent pass.
Install from PyPI with
pip install agentest-ai. Until it is live, install from GitHub:pip install git+https://github.com/srpadmanabhuni/agentest. A git clone is only needed when you want the examples folder and bundled walkthroughs. More options: install and quickstart.
Read a verdict: pass, fail, n/a
Every check prints one verdict and a detail line naming the evidence.
| Verdict | Meaning | What to do |
|---|---|---|
pass |
The check found the signal it needs and the behaviour met the rule. | Nothing. A pass is only as good as the inputs that were run. |
fail |
The check found the signal and the behaviour broke the rule. | Read the detail line, then triage (false positives, defect reports). |
n/a |
No signal to judge: the needed input is absent, or a needed fact is not declared. | Not a failure and never counted as a pass. If the check applies to your agent, add the input and re-run. |
Full guide: Reading the report (formats, detail lines, finding the rule behind an ID).
What it checks
130 checks: the 110 tests of the open Agentic AI Test Checklist 110 on Hugging Face, plus 20 repo extensions (X-001...X-020). See how agentest relates to the checklist.
Thirty opt-in New tests (NT-001...NT-030), plus the existing T1-020 and T1-021 designs, close 30 further article tests from The original 110 tests (37 of 110 fully covered). They stay out of the default 130; run them with agentest std run --ids NT. The mapping is in Article-test coverage.
Load the 47 highest-priority test designs in three lines (config all has all 110; details in Catalogue and Hugging Face):
from datasets import load_dataset
ds = load_dataset("srinivaspadmanabhuni/agentic-ai-test-checklist-110", "p0_smoke", split="train")
print(ds[0]["id"], ds[0]["title"]) # T1-001 Terminal postconditions hold after a single agent task
| Class | Checks | Catches, for example |
|---|---|---|
| T1 Task success and terminal state | 18 | Claims success it did not earn (T1-018); writes outside scope (T1-004) |
| T2 Dependency ordering | 14 | Irreversible action before its prerequisite (T2-001) |
| T3 Control handover and authorisation | 14 | Gated action with no recorded approval (T3-006) |
| T4 Prompt injection from untrusted documents | 18 | A hidden instruction changes who gets the email (T4-003) |
| T5 Tool-call allowlists | 18 | Undeclared tool or disallowed host (T5-001, T5-005) |
| T6 State drift across turns | 14 | An amount or ID silently changes between turns (T6-002, T6-003) |
| T7 Metamorphic and consistency | 14 | Personal data left unmasked (T7-014) |
| X Repo extensions | 20 | Extra checks, listed in the per-ID pages |
Packs and priorities. Run one class with --ids T4,T5, or list the CLI packs (security, privacy, functional and more, each with its test count) with agentest list --packs. On Hugging Face, p0_smoke holds the 47 P0 tests and ten topic packs group the same 110 tests; risk-based test planning lists every ID by priority: P0 first, then P1, P2 and the unprioritised extensions.
Learn more
| I want to | Go to |
|---|---|
| Work through a tutorial | Tutorials, tutorial index |
| Understand it in ten minutes | Why agentest: developers, testers |
| See a full bug-detection story | Demo: trace, failed check, evidence, corrected result |
| Walk through real failures | Walkthroughs |
| Install, CLI, config, CI | Getting started, User Guide, CI |
| Read a report | Reading the report |
| Test by hand or plan a test cycle | Tester quickstart, per-test guide, test planning, glossary |
| See every document | Documentation index, FAQ |
| Know how it works and where it stops | How it works and coverage, Roadmap |
| Browse the checklist | Hugging Face dataset, how GitHub and HF fit together, how agentest relates to the checklist |
Roadmap
Open source, in this repository. The full roadmap has the detail; it is a plan, not a commitment.
- Rule engine with 130 executable checks, deterministic and offline
- The 110-test checklist dataset on Hugging Face
- Validation method: blind, label-locked evaluation (how it works)
- CI gate (
--strict, JUnit and SARIF output) and a no-install Colab and browser demo - LangGraph importer and a worked example
- Opt-in New tests (
NT-001toNT-030) on main, plus T1-020 and T1-021 (agentest std run --ids NT) - Deeper framework adapters beyond the existing native-log importers (LangGraph, OpenAI Agents SDK, AutoGen, smolagents and n8n)
- Extension packs: multi-agent, privacy, red teaming, bias, explainability and data lineage
- PyPI release of
agentest-ai
Want to build one? See Contribute, including Help own a check family.
Contribute
You do not need to be an agent expert.
- Your first pull request: pick a
good first issueand follow the ten-minute first pull request. New to open source? Open the repo in a GitHub Codespace (set up for you). - Bring a trace: share a redacted agent trace in Discussions. Theme: Bring an agent trace, contribute a test.
- Wrong verdict? Use the issue forms.
- Contributor week, 23–30 Nov 2026 is the next push: ten starter issues, public credit and a leaderboard of merged pull requests. There is no money and there are no prizes.
- How we work: we reply within 24 hours and review within 48 hours (response promise). Please follow the Code of Conduct.
Help own a check family
We are looking for co-maintainers, one per area:
- Extension families: red teaming, privacy, bias, explainability, data lineage and multi-agent.
- Framework adapters: CrewAI, AutoGen, OpenAI Agents SDK, LangGraph and n8n.
To volunteer, comment on the contributor week Discussion. What an owner does is in CONTRIBUTING.md.
Contributors
AiEnsured agentest, an Agentic AI Testing platform, grows through the people who enhance and contribute. It is unique and relevant for responsible and safe AI agents because it checks what the agent actually did, not only what it said (why, with sources). Thank you to everyone below whose pull request is merged.
OscarTheWhiteHatHacker 📖 |
Mint0424 📖 |
Neeraj111010 🌐 📖 |
CyberKun 💻 📖 📖 💻 📖 |
HarshRajSinghania 📖 |
Key: 💻 code, ⚠️ tests, 📖 docs, 🌐 translation. Each badge links the merged pull request. The same list is in CONTRIBUTORS.md. The table is in the style of the all-contributors list, but we keep it by hand: no bot app. After your pull request merges, we add you; if we miss you, comment on your pull request.
Star history
If this saves you time, consider giving it a ⭐ to help others find it.
Related
Companions to this repository are listed in Where things live.
Author, citation, licence
By Dr Srinivas Padmanabhuni, CTO and Co-founder, AiEnsured (testAIng.com). Contact: srinivas AT testAIng.com. Cite with DOI 10.5281/zenodo.23597877 (all versions) or CITATION.cff; details in About. Runner: Apache-2.0 (LICENSE); checklist data: CC BY 4.0. Catalogue: pinned catalogue v1.3.1 (catalog/VERSION). Selected references; release highlights.
Awards (AiEnsured / testAIng): latest, Gold Winner, Best Use of AI for Responsible Leadership, Mint All About AI Tech4Good Awards 2026 (13 Nov 2026); earlier Forbes India 200 DGEMS (2025), Startup Maharathi Challenge winner (2025), TGS 100 Top 10 (2024) and more. Full list with sources.
Metadata
Release files for agentest-ai 3.5.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 |
|---|---|---|---|---|
| agentest_ai-3.5.0.tar.gz | 1.1 MB | With provenance | Details for agentest_ai-3.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentest_ai-3.5.0-py3-none-any.whl | Python 3 | none | any | Details for agentest_ai-3.5.0-py3-none-any.whl |
Total release size: 2.3 MB
Release files / agentest_ai-3.5.0.tar.gz
| Download URL | agentest_ai-3.5.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d1c1aeaccc383f3e883da421643e1dc4fb28b9faa81dbe3e05653313e2f2363a
|
|
BLAKE2b-256 checksum How to use checksums |
bb361dcbbf93e1c005ab89e1d27c987ed4c5342c157e08a61a61e8393f046dea
|
| 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 19, 2026.
Transparency logRelease files / agentest_ai-3.5.0-py3-none-any.whl
| Download URL | agentest_ai-3.5.0-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1c9db33eeafbddba1926acc0b62b36e9eb2882c0f94387007aba7e1de7b7e58b
|
|
BLAKE2b-256 checksum How to use checksums |
446c70c17f11456d9fb411440da927e3e0a81c8aaf8097529ccf84056ee946f3
|
| 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 19, 2026.
Transparency logSecurity for agentest-ai 3.5.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 agentest_ai-3.5.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 19, 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.