Skip to main content
Every tool call is automatically protected by a circuit breaker that stops repeated failures from wasting time.

​
Quick Start

1

Works by default

Circuit breaker protection is automatically enabled for every tool call with zero configuration needed.
from praisonaiagents import Agent

agent = Agent(
    name="Researcher",
    instructions="Research the topic",
    tools=[my_tool],  # Circuit breaker protects my_tool automatically
)

agent.start("Research quantum computing")
2

Detect open circuit

When a tool fails 5 times consecutively, subsequent calls return an error dictionary instead of calling the tool.
# If my_tool fails 5 times in a row, subsequent calls return:
# {
#     "error": "Tool 'my_tool' circuit breaker open - too many recent failures", 
#     "circuit_open": True,
#     "agent_name": "Researcher",
#     "session_id": "...",
#     "remediation": "Wait for recovery_timeout (60s) or investigate recent tool failures."
# }
3

Tune or reset

Customize circuit breaker behavior or reset all breakers between test runs.
from praisonaiagents.tools.circuit_breaker import (
    get_circuit_breaker, CircuitBreakerConfig, reset_all_circuit_breakers
)

# Tune circuit breaker for a specific tool
breaker = get_circuit_breaker(
    "tool_my_tool", 
    CircuitBreakerConfig(
        failure_threshold=3,  # Open after 3 failures instead of 5
        recovery_timeout=30.0,  # Try again after 30s instead of 60s
    )
)

# Reset all circuit breakers
reset_all_circuit_breakers()

​
How It Works

StateBehavior
CLOSEDNormal operation - all calls pass through
OPENTool calls blocked - returns error dict
HALF_OPENRecovery mode - limited probe calls allowed

​
Configuration Options

OptionTypeDefaultDescription
failure_thresholdint5Failures before opening
recovery_timeoutfloat60.0Seconds before half-open probe
success_thresholdint2Successes in half-open to close
timeoutfloat30.0Per-call timeout
monitor_windowfloat300.0Failure-rate window
enable_health_checkboolTruePeriodic health checks
health_check_intervalfloat30.0Health-check interval
graceful_degradationboolTrueReturn error dict instead of raising

​
What Does NOT Trip the Breaker

Circuit breakers ignore certain error types to avoid false positives:
  • Approval denied errors - User permission issues don’t indicate tool problems
  • Permission denied errors - Access control failures aren’t tool failures
  • Approval process errors - User workflow issues shouldn’t trigger circuit breaking
These errors are handled normally by the agent without affecting circuit breaker state.

​
Common Patterns

Monitor circuit breaker health and statistics for debugging.
from praisonaiagents.tools.circuit_breaker import get_circuit_breaker

# Get circuit breaker for a tool
breaker = get_circuit_breaker("tool_my_tool")

# Check current state and stats
print(f"State: {breaker.state}")
print(f"Failure count: {breaker.stats.failure_count}")
print(f"Success count: {breaker.stats.success_count}")
print(f"Total requests: {breaker.stats.total_requests}")
print(f"Rejected requests: {breaker.stats.rejected_requests}")

​
Best Practices

Circuit breakers prevent cascading failures and protect system stability. Keep them enabled in production environments to ensure reliable agent operation.
Track circuit breaker statistics in your monitoring systems. Frequent openings indicate underlying tool reliability issues that need attention.
Call reset_all_circuit_breakers() in test teardown to ensure clean state. This prevents test failures from affecting subsequent test runs.
When handling circuit_open: true responses, provide clear user feedback about temporary tool unavailability and suggest retry timeframes or alternative approaches.

Model Failover

Automatic LLM provider switching

Error Handling

Comprehensive error handling strategies