Agent Resilience Controller
A standalone Python utility designed to detect and break failure loops in automated systems and AI agents.
In autonomous workflows, agents can often fall into "infinite loops" when encountering a persistent error (like a syntax failure or a specific API rejection). This tool implements a Circuit Breaker pattern to monitor these patterns and trigger strategic shifts before resources are wasted.
⚙️ How it Works
The controller doesn't just count total errors; it fingerprints them:
Error Hashing: Every error message is passed through an MD5 hashing function to create a unique fingerprint.
Strike Tracking: The system maintains a localized counter for each unique fingerprint.
Strategic Tripping: When a specific error reaches the strike_limit, the circuit breaker trips.
Callback Execution: Upon tripping, the controller executes a registered callback, allowing the parent system to change its strategy (e.g., switching LLMs, reducing temperature, or alerting a human).
🛠️ Features
MD5 Signature Detection: Correcty identifies repeating errors even if the logs are interleaved with other data.
Strategy Callbacks: Decoupled logic—your main application defines what to do when the system fails, while this tool defines when to do it.
Non-Blocking Logic: Lightweight and designed to be integrated into any try/except block or event loop.
Zero Dependencies: Built entirely with Python's standard library (hashlib, logging).
🚀 Usage Guide
from agent_resilience_controller import AgentResilienceController
def switch_strategy(err_hash, msg): print(f"Switching to fallback model due to repeating error: {err_hash}")
resilience = AgentResilienceController(strike_limit=3) resilience.register_strategy_callback(switch_strategy)
while True: try: # Your agent logic here perform_task() resilience.clear_all() # Reset on success break except Exception as e: is_safe = resilience.track_failure(str(e)) if not is_safe: # Change state or break loop apply_fallback_logic()
💡 Engineering Rationale
This module is a critical component for Agentic Reliability. Without a localized circuit breaker, an autonomous system might repeat a doomed operation thousands of times. By fingerprinting errors, we allow the system to tolerate "flaky" one-off errors while immediately reacting to "systemic" repeating failures.
📄 License
This project is licensed under the MIT License. See the LICENSE file for details.
Developed by: Thiago L. Pereira (2026)