Skip to main content

AgentTrace Logo

AgentTrace 🛡️

The open-source circuit breaker for multi-agent AI pipelines.
Trace every action. Block hallucinations. Short-circuit before damage propagates.

PyPI version npm version MIT License Tests


"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.")

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

→ GitHub · npm


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

→ GitHub · Issues · Changelog

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)

Source distribution for ai-agenttrace 2.1.0
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)

Table of built distributions (wheels) for ai-agenttrace 2.1.0
File Interpreter ABI Platform Actions
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.

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