Tool Circuit Breaker

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

from praisonaiagents import Agent, tool

@tool
def flaky_api(query: str) -> str:
    """Call an external API."""
    return f"Results for: {query}"

agent = Agent(name="Researcher", tools=[flaky_api])
agent.start("Search quantum computing")  # circuit breaker protects automatically

Sync and Async Parity: Circuit breaker protection now applies uniformly to both sync and async tool execution paths. Previously, async calls bypassed circuit breaker checks.

This tool-level circuit breaker is separate from the new LLM idle-timeout circuit breaker, which protects against LLM provider stalls during model calls.

Per-agent scoping: breakers are now keyed per agent instance (tool_{id(self)}_{function_name}), so two agents that expose same-named tools (e.g. search) no longer share one breaker — one agent’s failures can’t degrade the other. Per-agent breakers are auto-pruned from the registry when the Agent is garbage-collected (via weakref.finalize), so a reused instance id can’t inherit a stale OPEN breaker — agent.close() / aclose() merely reclaims that space earlier.

The user triggers a flaky tool; repeated failures open the breaker so later calls fail fast instead of looping on errors.

Quick Start

Works by default

Circuit breaker protection is automatically enabled for every tool call with zero configuration needed.

from praisonaiagents import Agent, tool

@tool
def flaky_api(query: str) -> str:
    """Call an external API."""
    return f"Results for: {query}"

agent = Agent(
    name="Researcher",
    instructions="Research the topic",
    tools=[flaky_api],
)

agent.start("Research quantum computing")

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."
# }

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

State	Behavior
CLOSED	Normal operation - all calls pass through
OPEN	Tool calls blocked - returns error dict
HALF_OPEN	Recovery mode - limited probe calls allowed

Configuration Options

Option	Type	Default	Description
`failure_threshold`	`int`	`5`	Failures before opening
`recovery_timeout`	`float`	`60.0`	Seconds before half-open probe
`success_threshold`	`int`	`2`	Successes in half-open to close
`timeout`	`float`	`30.0`	Per-call timeout
`monitor_window`	`float`	`300.0`	Failure-rate window
`enable_health_check`	`bool`	`True`	Periodic health checks
`health_check_interval`	`float`	`30.0`	Health-check interval
`graceful_degradation`	`bool`	`True`	Return 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.

Lifecycle

Per-agent breakers are pruned from the global registry automatically when the Agent is garbage-collected — a weakref.finalize callback is registered when each breaker is created. This closes the CPython id()-reuse window without requiring agent.close() / agent.aclose() to be called explicitly. Calling agent.close() / agent.aclose() still triggers the same cleanup earlier and deterministically — recommended when you know the agent is done and want registry space reclaimed immediately.

Common Patterns

Observability
Custom Config Per Tool
Global Reset

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

Apply different circuit breaker settings to different tools based on their reliability characteristics.

from praisonaiagents.tools.circuit_breaker import get_circuit_breaker, CircuitBreakerConfig

# Strict config for unreliable external APIs
strict_config = CircuitBreakerConfig(
    failure_threshold=2,    # Open quickly
    recovery_timeout=120.0,  # Wait longer before retry
)
api_breaker = get_circuit_breaker("tool_external_api", strict_config)

# Lenient config for internal tools
lenient_config = CircuitBreakerConfig(
    failure_threshold=10,   # Allow more failures
    recovery_timeout=30.0,  # Recover quickly
)
internal_breaker = get_circuit_breaker("tool_internal_db", lenient_config)

Reset all circuit breakers after deployments or system maintenance.

from praisonaiagents.tools.circuit_breaker import reset_all_circuit_breakers

# Reset all breakers (useful for test cleanup or after deployment)
reset_all_circuit_breakers()

# Or reset individual breakers
from praisonaiagents.tools.circuit_breaker import get_circuit_breaker
breaker = get_circuit_breaker("tool_my_tool")
breaker.reset()

Best Practices

Don't disable in production

Circuit breakers prevent cascading failures and protect system stability. Keep them enabled in production environments to ensure reliable agent operation.

Monitor circuit breaker stats

Track circuit breaker statistics in your monitoring systems. Frequent openings indicate underlying tool reliability issues that need attention.

Reset between test runs

Per-agent breakers are auto-pruned when the Agent is collected (via weakref.finalize). Explicit agent.close() reclaims registry space immediately. reset_all_circuit_breakers() remains the sledgehammer for global tests that need a clean slate regardless of GC timing.

Surface circuit_open to users

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

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Tool Circuit Breaker

Quick Start

How It Works

Configuration Options

What Does NOT Trip the Breaker

Lifecycle

Common Patterns

Best Practices

Model Failover

Error Handling

​Quick Start

​How It Works

​Configuration Options

​What Does NOT Trip the Breaker

​Lifecycle

​Common Patterns

​Best Practices

​Related

Model Failover

Error Handling

Quick Start

How It Works

Configuration Options

What Does NOT Trip the Breaker

Lifecycle

Common Patterns

Best Practices

Related