Skip to main content

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.

Demo: an agent says "added to the cart", its trace shows no add_to_cart call and an empty cart, and agentest reports a fail on check T1-018

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.

CI License: Apache-2.0 Python 3.11+ Docs Hugging Face checklist Open In Colab Try in browser

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.

  1. Install from PyPI, from GitHub, or from a clone of this repository.
  2. 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).
  3. 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):

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 --strict makes it a one-line CI gate.
  • QA and testers: 130 ready-made executable checks with deterministic pass / fail / n/a verdicts 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: --strict exits 1 on any fail; 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.

Four failed checks on the buggy sample agent. T1-018: claims success. T2-001: place_refill before verify_identity. T4-003: injected recipient audit@evil.example. T7-014: unmasked email.

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-001 to NT-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.

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
OscarTheWhiteHatHacker

📖
Mint0424
Mint0424

📖
Neeraj111010
Neeraj111010

🌐 📖
CyberKun
CyberKun

💻 📖 📖 💻 📖
HarshRajSinghania
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.

Star history of srpadmanabhuni/agentest

Companions to this repository are listed in Where things live.

Author, citation, licence

Built by
AiEnsured    testAIng

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)

Source distribution for agentest-ai 3.5.0
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)

Table of built distributions (wheels) for agentest-ai 3.5.0
File Interpreter ABI Platform Actions
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 log

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

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

Select from 2 files

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

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