AgentTrace 🛡️
The open-source circuit breaker for multi-agent AI pipelines.
Trace every action. Block hallucinations. Short-circuit before damage propagates.
"Agent 1 made an error. Agent 2 built on it. Agent 3 executed it. All three returned status 200. Nobody knew."
AgentTrace is the circuit breaker your AI pipeline is missing.
Why AgentTrace
| Everyone else | AgentTrace |
|---|---|
| Observability (logs what happened) | Accountability (blocks what shouldn't happen) |
| Single-agent guardrails | Cross-agent circuit breaker |
| Cloud-dependent | Zero-cloud, local NDJSON, self-hosted forever |
| Post-mortem debugging | Pre-mortem intervention |
Quick Start — Python
pip install ai-agenttrace
# With OpenAI explainer support:
pip install "ai-agenttrace[openai]"
import asyncio
from agenttrace import AgentTrace, AgentTraceOptions
guard = AgentTrace(AgentTraceOptions(
rules=["block_pii_leakage", "block_harmful_content", "block_hallucination"],
persist=True, # saves to .agenttrace/traces.ndjson
))
async def my_agent(prompt: str) -> str:
# your LLM call here
return "Agent response..."
async def main():
result = await guard.guard_fn(
lambda: my_agent("Process customer request"),
original_input="Process customer request"
)
if result.blocked:
print(f"BLOCKED: {result.reason}")
print(f"Risk: {result.risk_level}")
print(f"Audit ID: {result.audit_id}")
else:
print(result.result) # safe to use
print(result.explanation) # "Agent processed refund. Risk: LOW."
asyncio.run(main())
Multi-Agent Pipeline — Circuit Breaker
The key feature: when Agent 1 (researcher) is blocked, Agent 2 (drafter) and Agent 3 (executor) never run.
from agenttrace import AgentTrace, AgentTraceOptions, AgentPipeline, PipelineStage
pipeline = AgentPipeline(
name="medical-decision-support",
agents=[
PipelineStage(
name="researcher",
guard=AgentTrace(AgentTraceOptions(
rules=["block_hallucination"],
context=["Metformin max dose: 2000mg/day per FDA."],
)),
agent=researcher_agent,
),
PipelineStage(
name="drafter",
guard=AgentTrace(AgentTraceOptions(rules=["block_pii_leakage"])),
agent=drafter_agent,
),
PipelineStage(
name="executor",
guard=AgentTrace(AgentTraceOptions(rules=["require_human_approval"])),
agent=executor_agent,
),
],
on_stage_complete=lambda name, result: print(f"[{name}] {'⛔ BLOCKED' if result.blocked else '✅ OK'}"),
)
result = await pipeline.run("Patient needs medication review")
if result.short_circuited:
print(f"Pipeline blocked at: {result.blocked_at}")
print(f"Downstream agents were NOT run.")
else:
print(f"All {len(result.stages)} stages completed.")
AgentPipelineis available in Python as of v2.1 — full parity with TypeScript.
Built-in Rules
14 rules covering safety, privacy, security, and compliance — all run in parallel with <1ms overhead on the happy path.
| Rule | Category | Severity |
|---|---|---|
block_pii_leakage |
Privacy | HIGH–CRITICAL |
block_special_category_data |
Privacy (GDPR Art 9) | HIGH–CRITICAL |
block_harmful_content |
Safety | HIGH–CRITICAL |
block_medical_advice |
Professional | CRITICAL |
block_legal_advice |
Professional | HIGH |
block_financial_advice |
Professional | HIGH |
block_hallucination |
Quality / Grounding | HIGH |
block_prompt_injection |
Security (OWASP LLM01) | CRITICAL |
block_system_prompt_leakage |
Security (OWASP LLM07) | HIGH |
block_discrimination |
Fairness (EU Charter) | CRITICAL |
block_manipulation |
EU AI Act Art 5 | HIGH–CRITICAL |
block_ai_identity_deception |
EU AI Act Art 50 | CRITICAL |
require_human_approval |
Oversight | HIGH–CRITICAL |
block_token_budget_exceeded |
Resource (OWASP LLM10) | HIGH–CRITICAL |
Compliance Bundles
from agenttrace import AgentTrace, AgentTraceOptions
# Pre-configured bundles — no need to list rules manually
guard = AgentTrace(AgentTraceOptions(
rules="OWASP_LLM", # or: EU_AI_ACT | HEALTHCARE | FINANCE | ALL
))
Available bundles: EU_AI_ACT, OWASP_LLM, HEALTHCARE, FINANCE, ALL
Hallucination Detection
The block_hallucination rule checks outputs against your provided context — no LLM needed:
result = await guard.guard_fn(
lambda: my_agent(prompt),
original_input=prompt,
# Pass your RAG context so the rule can check grounding:
# context=["The maximum dose is 2000mg per day per FDA guidelines."]
)
# If agent says "8000mg" → CRITICAL, confidence 0.98, BLOCKED
Detection approach:
- Splits output into sentences
- Finds factual assertion markers
- Extracts numeric values and unit-normalizes them
- Computes word-overlap with provided context
- Mismatch → violation with confidence score
Audit Trail
Every run is stored in .agenttrace/traces.ndjson — append-only, local, zero cloud:
{
"audit_id": "1a552b8e-ddb0-4e0e-b05a-bb3ea38a2a0f",
"blocked": true,
"risk_level": "CRITICAL",
"violations": [{"rule": "block_hallucination", "severity": "CRITICAL"}],
"timestamp": "2026-05-30T09:42:11.334Z"
}
View the live dashboard:
# Install Node.js package for the dashboard CLI
npx @hackerx333/agenttrace ui
# Opens at http://localhost:5173
Shadow Mode
Detect violations without blocking — for production monitoring before you enforce:
guard = AgentTrace(AgentTraceOptions(
rules=["block_pii_leakage", "block_hallucination"],
enforcement_mode="shadow", # logs violations, never blocks
persist=True,
))
Wrapping a LangChain Agent
from langchain.agents import initialize_agent
from agenttrace import AgentTrace, AgentTraceOptions
agent = initialize_agent(tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION)
guard = AgentTrace(AgentTraceOptions(rules=["block_pii_leakage", "block_harmful_content"]))
# Wrap the agent — same interface, now accountable
safe_agent = guard.wrap(agent)
result = await safe_agent.invoke("Process this customer request")
Architecture
Your Agent
│
▼ (Python wrap / guard_fn)
┌───────────────────────────────────────┐
│ AgentTrace │
│ │
│ ┌──────────┐ ┌───────────────────┐ │
│ │ Tracer │ │ Rule Engine │ │
│ │ (steps) │ │ (asyncio gather) │ │
│ └──────────┘ │ 14 built-in rules│ │
│ └───────────────────┘ │
│ ┌──────────┐ ┌───────────────────┐ │
│ │ Explainer│ │ Store │ │
│ │(optional)│ │ (.ndjson local) │ │
│ └──────────┘ └───────────────────┘ │
└───────────────────────────────────────┘
│
▼
GuardedResult {
blocked, reason, explanation,
risk_level, audit_id, audit_trail,
violations, result
}
TypeScript / Node.js SDK
For the full feature set including AgentPipeline (circuit breaker), real-time dashboard, and 200+ tests:
npm install @hackerx333/agenttrace
npx @hackerx333/agenttrace ui # launch dashboard
Roadmap
-
v2.1— Hash-chain audit trail, input validation, rate limiting, Python AgentPipeline ✅ - v2.2 — Semantic hallucination detection (embedding similarity)
- v3.0 — Cloud dashboard + team access
License
MIT © 2026 AgentTrace Contributors
Metadata
Release files for ai-agenttrace 2.1.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 |
|---|---|---|---|---|
| ai_agenttrace-2.1.0.tar.gz | 14.2 kB | Without provenance | Details for ai_agenttrace-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_agenttrace-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for ai_agenttrace-2.1.0-py3-none-any.whl |
Total release size: 29.7 kB
Release files / ai_agenttrace-2.1.0.tar.gz
| Download URL | ai_agenttrace-2.1.0.tar.gz |
|---|---|
| Size | 14.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
056bc1361ef51f95952b248ce82552479c53df4a43c89f42c25926efcd34df34
|
|
BLAKE2b-256 checksum How to use checksums |
4f2abfd3886cdc06ba82ddd2447033e3f00667c95bbd4fdb1064103257ad7eda
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.0
|
Release files / ai_agenttrace-2.1.0-py3-none-any.whl
| Download URL | ai_agenttrace-2.1.0-py3-none-any.whl |
|---|---|
| Size | 15.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ca8f1ec73418e530f1122d41ff25f032c06311bd1d435aa87a0ba7dc0659732b
|
|
BLAKE2b-256 checksum How to use checksums |
69888b9ddd10c385be6df2302d3e416c33bd3bd03686a6ab8f2e47e494924abc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.0
|
Security for ai-agenttrace 2.1.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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.