agentchaos-tools

Chaos testing for agentic AI — fault injection hooks for openai-agents-python.

Simulate tool failures, latency, and corrupted outputs to verify your agent handles real-world conditions gracefully.

Install

pip install agentchaos-tools

Usage

from agents import Agent, Runner, function_tool
from agentchaos import FaultInjectionHooks, ToolFault, FaultType

@function_tool
def web_search(query: str) -> str:
    return f"Results for {query}"

agent = Agent(name="assistant", tools=[web_search])

hooks = FaultInjectionHooks(
    faults=[
        ToolFault(tool_name="web_search", fault_type=FaultType.EXCEPTION, rate=0.5),
        ToolFault(tool_name="calculator", fault_type=FaultType.LATENCY, latency_seconds=2.0),
    ],
    seed=42,  # optional: reproducible fault patterns
)

result = await Runner.run(agent, "Search for something", hooks=hooks)
hooks.report()
# agentchaos-tools report — 1 fault(s) triggered:
#   1. [EXCEPTION] tool='web_search'

Fault types

Type	What it does
EXCEPTION	Raises RuntimeError before the tool runs
LATENCY	Injects asyncio.sleep delay before the tool runs
CORRUPTION	Records that output was corrupted (visible in report)

Parameters

Parameter	Type	Default	Description
tool_name	str	required	Name of the tool to target
fault_type	FaultType	required	Type of fault to inject
rate	float	1.0	Probability (0.0–1.0) that the fault fires
latency_seconds	float	1.0	Delay in seconds (LATENCY only)
seed	int	None	Random seed for reproducible tests

License

MIT