CONCEPT What a circuit breaker does
A circuit breaker wraps a tool or sub-agent and watches its error rate. Once failures cross a threshold, the breaker trips and stops sending calls to that component for a cooldown — failing fast (or falling back) instead of hammering a dead dependency. This is the direct fix for the cascade failure mode from 6.1: it prevents wasted calls and stops one broken component from dragging down the rest.
DIAGRAM The three-state machine
(N failures) Open --> HalfOpen: cooldown elapsed HalfOpen --> Closed: trial call succeeds HalfOpen --> Open: trial call fails note right of Closed: calls flow through normally note right of Open: calls are blocked / fall back
fail fast, no wasted calls note right of HalfOpen: let ONE trial call through
| State | Behaviour | Transition out |
|---|---|---|
| Closed | Normal — calls pass through; failures are counted | → Open after N failures (threshold crossed) |
| Open | Tripped — calls are blocked and fail fast / fall back immediately | → Half-open once the cooldown timer elapses |
| Half-open | Trial — let a single probe call through | Success → Closed; failure → back to Open |
CODE A minimal breaker wrapper
Wrap any callable — an SDK call or a tool. The breaker short-circuits when open, probes when half-open, and resets on a successful probe.
import time, anthropic class CircuitBreaker: def __init__(self, threshold=5, cooldown=30): self.threshold, self.cooldown = threshold, cooldown self.failures = 0 self.state = "closed" self.opened_at = 0.0 def call(self, fn, *args, **kw): if self.state == "open": if time.monotonic() - self.opened_at < self.cooldown: raise RuntimeError("circuit open — failing fast") # no wasted call self.state = "half-open" # cooldown elapsed → probe try: result = fn(*args, **kw) except Exception: self._on_failure() raise self._on_success() # closed / probe passed return result def _on_failure(self): self.failures += 1 if self.state == "half-open" or self.failures >= self.threshold: self.state, self.opened_at = "open", time.monotonic() # trip def _on_success(self): self.failures, self.state = 0, "closed" # reset # Usage: guard a flaky tool so its outages can't cascade. breaker = CircuitBreaker(threshold=5, cooldown=30) def run_search_tool(query): return breaker.call(flaky_search_api, query)
400 invalid_request is your
bug and will fail identically on retry — tripping on it just hides the real error. Trip on transient/dependency
failures (5xx, 529, connection, timeouts), not on 4xx client errors (see 6.3).TRADE-OFFS Sensitivity of the threshold
✅ Trip early (low threshold / short cooldown)
- Stops cascades fast; sheds load quickly
- Recovers responsiveness for the rest of the system
⚠️ Trip early — the cost
- A brief blip can open the circuit and block healthy traffic
- Too-short cooldown flaps between open/half-open
- May trigger fallback/degradation more often than needed
EXAM TRAPS
PRACTICE
Q1 · Which state lets exactly one probe call through, and what happens on each outcome?
Half-open. It permits a single trial call. Success → transition to closed (resume normal traffic); failure → back to open and restart the cooldown.
Q2 · Should a circuit breaker count HTTP 400 errors toward its threshold?
No. A 400 is a client-side invalid_request that will fail identically every time —
it's not a dependency outage. Tripping on it masks a bug you should fix. Count transient/dependency failures
(5xx, 529, connection errors, timeouts).
Q3 · Breaker and retry are both configured on the same tool. How do they interact?
They compose at different scopes. Retry handles a single transient call (rung 1). The breaker tracks the aggregate error rate across calls and, once tripped, stops even attempting retries — which is what prevents retry storms from cascading.