Agent Reliability Advanced

Agent Reliability — Anti-Patterns

This skill extends agent-reliability with common mistakes and how to fix them. Load agent-reliability first.

When to Activate

• Retry logic catches authentication or validation errors (not just transient ones)
• All agent calls use the same fixed sleep delay on failure
• A single global timeout governs tool calls, agent calls, and entire workflows
• Circuit breaker opens after every single failure
• Every agent call uses the most expensive model regardless of task complexity

---

Anti-Patterns

Retrying Non-Retryable Errors (Auth, Validation)

Wrong:

async function callAgent(fn: () => Promise): Promise {
  for (let i = 0; i  Promise): Promise {
  return withRetry(fn, { retryableErrors: isRetryable })
}

Why: Retrying authentication or validation errors wastes time, inflates cost, and can trigger account lockouts — only transient infrastructure errors warrant retry.

---

Fixed Sleep Instead of Exponential Backoff with Jitter

Wrong:

for (let i = 0; i  { throw new Error('timeout') }),
])

Correct:

// Nested timeouts — each level has its own proportional budget
const toolResult = await callToolWithTimeout(tool, 15_000)   // tool: 15s
const agentResult = await runAgentWithTimeout(agent, 60_000) // agent: 60s
const workflowResult = await runAgentWithTimeout(           // workflow: 10min
  () => runWorkflow(goal), 10 * 60 * 1000
)

Why: A single shared timeout either aborts long workflows prematurely or lets runaway tool calls consume the entire budget — layered timeouts bound each level independently.

---

Opening a Circuit Breaker Too Aggressively (Low Threshold)

Wrong:

const breaker = new CircuitBreaker(1, 60_000)  // opens after a single failure
// One transient error now blocks all subsequent calls for 60 seconds

Correct:

const breaker = new CircuitBreaker(5, 60_000)  // opens after 5 consecutive failures
// Transient errors are retried; the circuit opens only on sustained failure

Why: A threshold of 1 treats every transient error as a sustained outage, causing unnecessary downtime; calibrate the threshold to distinguish spikes from real failures.

---

Using Opus for Every Agent Call Regardless of Complexity

Wrong:

async function classifyTaskComplexity(task: string): Promise {
  const response = await client.messages.create({
    model: 'claude-opus-latest',  // ~15x cost of Haiku for a three-word answer
    system: 'Reply with "simple", "medium", or "complex".',
    messages: [{ role: 'user', content: task }],
    max_tokens: 10,
  })
  return response.content[0].text.trim() as TaskComplexity
}

Correct:

async function classifyTaskComplexity(task: string): Promise {
  const response = await client.messages.create({
    model: 'claude-haiku-latest',  // lightweight model for lightweight classification
    system: 'Reply with exactly "simple", "medium", or "complex".',
    messages: [{ role: 'user', content: task }],
    max_tokens: 10,
  })
  return response.content[0].text.trim() as TaskComplexity
}

Why: Model selection should match task complexity — using Opus for trivial routing wastes budget that should be reserved for tasks requiring deep reasoning.

Reference

• agent-reliability — retry with exponential backoff, timeout hierarchies, fallback chains, circuit breaker, cost control, observability
• multi-agent-patterns — orchestration, routing, parallelization, handoffs

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: marvinrichter
• Source: marvinrichter/clarc
• License: MIT
• Homepage: https://marvinrichter.github.io/clarc

Install and usage instructions live in the source repository linked above.