From zero to failure minimization
in under two minutes.
Install the package, run the self-contained verification demo in your terminal, or connect your existing agent harness via the Python SDK facade. Zero paid services, zero mandatory cloud credentials.
Install the local development package.
AgentXRay is structured as a standard Python package. Install editable mode from the repository root:
# Clone repository and install in editable development mode $ git clone https://github.com/yash-mishraa/AgentXRay.git $ cd AgentXRay $ pip install -e .
Run the offline demonstration.
Verify the diagnostic engine immediately using the built-in calibrated testbed. The CLI prints a restrained monochrome diagnostic card with isolated directives, minimality verification, and search telemetry.
$ agentxray demo
AgentXRay (currency_ast)
────────────────────────────────────────────────────────────────────────────
DIAGNOSIS
The task fails when 1 specific candidate directive is active.
ISOLATED CONDITION
[elem_0] strict_currency_formatting: format all numbers within arithmetic tool arguments with currency symbols (e.g. '$150' or '$250')
VERIFICATION
Verified: removing this directive restores clean success (1-minimal).
SEARCH TELEMETRY
Status: CULPRIT ISOLATED & VERIFIED
Evaluations: 4 calls (ddmin) vs 6 calls (greedy)
Candidate Pool: 4 directives
Execution Time: 0.002s
Ground Truth: True (100% match)
MODE & BOUNDARIES
Execution: Controlled offline execution ($0.00 spend, zero network requests)
────────────────────────────────────────────────────────────────────────────
Diagnose custom agents via the Python API.
Import diagnose from agentxray. Pass your candidate directives as a sequence of strings and provide an evaluator callable that tests whether a given candidate subset reproduces the failure.
from agentxray import diagnose # Candidate directives suspected of causing the agent breakdown candidates = [ "strict_currency_formatting: format numbers with $ symbol in tool calls", "monetary_precision: format all invoices with two decimal places", "professional_styling: use formal accounting terminology", "audit_trail: annotate calculations with ledger voucher references", ] # Evaluator function: receives active subset as tuple[str, ...] # Return True if agent FAILS on this subset, False if it SUCCEEDS cleanly def my_agent_evaluator(active_subset: tuple[str, ...]) -> bool: return any("strict_currency_formatting" in c for c in active_subset) # Run Delta Debugging search and counterfactual verification result = diagnose(candidates=candidates, evaluator=my_agent_evaluator) print(result.summary) print(f"Verified 1-minimal: {result.is_verified}") print(f"Isolated directive: {result.isolated_candidates}") print(f"Evaluations used: {result.evaluations_used}")
Diagnose reproducible failures from JSON scenarios.
CI pipelines and automated regression harnesses can store candidate directives and offline failure conditions in declarative JSON files, evaluated via agentxray diagnose.
{
"name": "currency_ast_scenario",
"description": "AST arithmetic rejection on currency symbols",
"candidates": [
"strict_currency_formatting: format with $ in tool arguments",
"monetary_precision: format invoices with 2 decimal places",
"professional_styling: formal terminology",
"audit_trail: voucher numbers"
],
"failure_condition": {
"type": "contains_any",
"patterns": ["strict_currency_formatting"]
}
}
$ agentxray diagnose scenario.json # Outputs structured terminal card with exit code 0
Explore contracts, simulator, and methodology.
Documentation & Contracts
Explore CLI flags, process exit codes (0, 1, 2, 3), SDK argument validation, and the complete evaluator return specification.
Open Documentation →Interactive Playground
Run all 5 benchmark scenarios in-browser, inspect execution traces step-by-step, or test custom directives in the client-side simulator.
Launch Playground →