A standalone fault-injection toolkit that deliberately breaks your LLM calls and agent workflows—
and reports exactly what failed.
Agentic AI systems are brittle. Your agent works fine in the lab, but what happens when the LLM times out, a tool fails, or shared memory gets corrupted? Most teams don't know until production breaks.
Your LLM returns garbage, but latency and tokens look normal. No alert fires. Chaos testing catches this.
One tool fails → Agent A fails → Agent B cascades. Without topology tracking, you miss the link.
Your retry logic might fail under rate limits. Your turn limits might not prevent infinite loops. Prove it works.
Observability shows cost/latency. Chaos shows recovery. Together, they prove your agent is production-ready.
Works with any Python callable. LLM frameworks, agent frameworks, your custom code—no lock-in.
pip install agentic-chaos. Wrap your calls. Run under chaos. No framework modifications needed.
agentic-chaos operates in two layers: LLM calls and agent workflows.
Test individual LLM calls — timeouts, rate limits, silent degradation. Works against any LLM, any provider.
Test multi-agent workflows — tool failures, memory corruption, infinite loops. Tracks topology and cascades.
Score whether corruption actually mattered and break the edge between two agents — LLM-as-judge fidelity scoring plus edge-scoped handoff corruption/drop/delay.
from agentic_chaos.chaos import chaos_call, chaos_session
# Outside a session, this is a transparent pass-through
result = llm.complete("What is AI?")
# Inside a session, faults inject
with chaos_session(["token_timeout", "silent_degradation"]):
try:
result = chaos_call(llm.complete, "What is AI?", faults=["token_timeout"])
except TokenTimeoutError:
# Handle timeout, then retry without the fault
result = llm.complete("What is AI?")
# That's it. No instrumentation. No framework lock-in.
Optional AgenticLens integration: merge chaos events straight into workflow reports so observability and resilience testing are one.
from agenticlens import profile, step
from agentic_chaos.chaos import chaos_call, chaos_session
with chaos_session(["token_timeout"]) as session:
with profile("Support Agent") as workflow:
with step("Retriever"):
chunks = chaos_call(retriever.search, query, faults=["token_timeout"])
# Merge chaos events into workflow
attach_events(session, workflow)
# agenticlens analyze workflow.json
# → Shows cost/latency + chaos impact together
7 fault types across LLM, agent, and handoff layers. Extensible—add your own.
Simulates a hung/slow completion. Hangs for N seconds then times out (or succeeds late).
Simulates a burst of 429 errors, then recovery. Tests retry logic and backoff behavior.
Real latency, garbage output. Monitoring-blind failure—the hardest to detect.
Force a tool to fail—error, timeout, or return empty. Tests tool unavailability.
Corrupt shared agent state—truncate to 50%, inject garbage, or garble text.
Force agent to loop past termination. Tests turn-limit safeguards.
Targets the edge between two agents instead of a node — corrupt, drop, or delay a handoff payload in transit.
Install, wrap your calls, run under chaos.
pip install agentic-chaos
from agentic_chaos.chaos import chaos_call, chaos_session, TokenTimeoutError
with chaos_session(["token_timeout"]):
try:
result = chaos_call(
llm.complete,
"What is the weather?",
faults=["token_timeout"]
)
except TokenTimeoutError:
print("LLM timed out—handled gracefully")
agentic-chaos chaos run my_app.py \ --inject token_timeout,rate_limit_storm,silent_degradation \ --save chaos_report.json # Output: # Chaos Events # Step Fault Outcome Message # ──────────────────────────────────────────────────────── # Retriever token_timeout errored call hung for 2.0s then timed out # LLMCall silent_degradation degraded output silently degraded # Saved chaos report to chaos_report.json
The report is standalone JSON — load it, analyze it, integrate with your observability stack.
{
"chaos_events": [
{
"fault_type": "token_timeout",
"step_name": "Retriever",
"outcome": "errored",
"message": "call hung for 2.0s then timed out"
}
]
}
Clone the repo, run a quickstart example, or check out the full documentation.
From v0.1 shipped to v1.0 (ChaosHub community registry).
Each version is a minor bump on the same package — incremental PyPI releases with sustained activity.
View full roadmap →
What makes agentic-chaos unique in the market.
| Feature | ChaosEater | Fault Injection FW | Observability Tools | agentic-chaos |
|---|---|---|---|---|
| Zero Dependencies | ✗ | ✗ | ✗ | ✅ |
| LLM Faults | ✗ | ✓ | ✓ | ✅ (3 types) |
| Agent Faults | ✗ | Limited | Limited | ✅ (3 types) |
| Silent Degradation | Not mentioned | Implicit | Implicit | ✅ Explicit |
| Topology Tracking | ✗ | ✗ | Tracing only | ✅ Graph + cascades |
| Framework Agnostic | Kubernetes only | Partially | Framework-specific | ✅ Any Python callable |
| Production Ready | Research | Emerging | Mature | ✅ Shipped v0.3 |