circuit-breaker-pattern

Circuit Breaker Pattern

Graceful degradation when tools fail. An agent that calls five tools and one is broken should not fail entirely — it should recognize the broken tool, stop calling it, reduce scope to what remains achievable, and report honestly about what was skipped. This skill codifies that logic using the circuit breaker pattern from distributed systems, adapted to agentic tool orchestration.

The core insight, from kirapixelads' "Kitchen Fire Problem": the expeditor (orchestration layer) must not cook. Separation of concerns between deciding what to attempt and how to attempt it prevents the orchestrator from getting trapped in a failing tool's retry loop.

When to Use

• Building agents that depend on multiple tools with varying reliability
• Designing fault-tolerant agentic workflows where partial results are better than total failure
• An agent is stuck in a retry loop on a broken tool instead of continuing with working tools
• Recovering gracefully from tool outages mid-task
• Hardening existing agents against cascading tool failures
• Stale or cached tool output is being treated as fresh data

Inputs

• Required: List of tools the agent depends on (names and purposes)
• Required: The task the agent is trying to accomplish
• Optional: Known tool reliability issues or past failure patterns
• Optional: Failure threshold (default: 3 consecutive failures before opening circuit)
• Optional: Failure budget per cycle (default: 5 total failures before pause-and-report)
• Optional: Half-open probe interval (default: every 3rd attempt after opening)

Procedure

Step 1: Build the Capability Map

Declare what each tool provides and what alternatives exist. This map is the foundation for scope reduction — without it, a tool failure leaves the agent guessing about what to do next.

capability_map:
  - tool: Grep
    provides: content search across files
    alternatives:
      - tool: Bash
        method: "rg or grep command"
        degradation: "loses Grep's built-in output formatting"
      - tool: Read
        method: "read suspected files directly"
        degradation: "requires knowing which files to check; no broad search"
    fallback: "ask the user which files to examine"

  - tool: Bash
    provides: command execution, build tools, git operations
    alternatives: []
    fallback: "report commands that need to be run manually"

  - tool: Read
    provides: file content inspection
    alternatives:
      - tool: Bash
        method: "cat or head command"
        degradation: "loses line numbering and truncation safety"
    fallback: "ask the user to paste file contents"

  - tool: Write
    provides: file creation
    alternatives:
      - tool: Edit
        method: "create via full-file edit"
        degradation: "requires file to already exist for Edit"
      - tool: Bash
        method: "echo/cat heredoc"
        degradation: "loses Write's atomic file creation"
    fallback: "output file contents for the user to save manually"

  - tool: WebSearch
    provides: external information retrieval
    alternatives: []
    fallback: "state what information is needed; ask user to provide it"