model-routing-patterns

name	model-routing-patterns
description	Multi-model pipelines (Haiku/Sonnet/Opus): cost routing, escalation, fallback chains. Triggers: model routing, Haiku, Sonnet, Opus, escalation, fallback chain.
effort	medium
user-invocable	false
allowed-tools	Read

Model Routing Patterns

Three Claude tiers. Using Opus for everything is 10-40x more expensive than it needs to be. Using Haiku for everything loses accuracy on hard tasks. The craft is routing.

Model Characteristics (2026)

Model	$/1M in·out	Cost (rel.)	Strengths	When
Haiku 4.5	$1 / $5	1x	Classification, extraction, simple tools, moderation	Bulk processing, triage, labels
Sonnet 5	$3 / $15	~3x	General coding, reasoning, most agent tasks	Default workhorse
Opus 4.8	$5 / $25	~5x	Complex reasoning, orchestration, architecture, large context	Hard, rare, high-stakes
Fable 5	$10 / $50	~10x	Most demanding long-horizon agentic work	Only when explicitly chosen

Prices are per 1M tokens; ratios are approximate and shift between releases. Re-check pricing before committing a production path.

Fable 5 is not the default "best model". Its price sits above Opus-tier, and Opus 4.8 is state-of-the-art on planning/orchestration at half the input and output cost. Reach for Fable 5 only when the user explicitly asks for it or a benchmarked task genuinely needs it — for "use the strongest model", the target is claude-opus-4-8.

Effort — the cheaper lever before swapping models

On Fable 5 / Opus 4.8 / Sonnet 5, output_config.effort (low | medium | high | xhigh | max) controls thinking depth and token spend without changing the model — so it does not invalidate the prompt cache the way a mid-session model swap does. Tune effort first; drop to a cheaper model only when effort alone can't hit the cost target.

Effort	Use for
low	Latency-sensitive, non-intelligence-sensitive: chat, simple lookups, cheap subagents
medium	Cost-conscious step-down from the default
high	Default for most intelligence-sensitive work (a good quality/cost balance)
xhigh	Hardest coding and agentic tasks (Claude Code's default)
max	Correctness matters more than cost; test for diminishing returns

In our agents, effort is set per skill/agent frontmatter (effort:), not swapped at runtime. Combine effort routing with model routing: e.g. sonnet at high often beats opus at low for cost-equal quality — benchmark before committing.

Pattern 1 — Complexity Router (pre-classify)

Cheap model classifies the request, then routes to the right tier:

def route(user_message: str) -> str:
    complexity = classify_with_haiku(user_message)  # returns: simple | medium | hard
    return {"simple": "haiku", "medium": "sonnet", "hard": "opus"}[complexity]

Good when ~60% of traffic is simple. Overhead: one Haiku call per request (~100 tokens).

Pattern 2 — Confidence-Based Escalation

Try the cheap model first, escalate only when it hesitates:

def solve(problem: str):
    haiku = call_haiku(problem)
    if haiku.confidence > 0.85:
        return haiku.answer
    sonnet = call_sonnet(problem + haiku.reasoning)
    if sonnet.confidence > 0.8:
        return sonnet.answer
    return call_opus(problem)

Haiku must be prompted to output confidence (e.g. via tool-use structured output — see json-mode-patterns). Pure self-reported confidence is noisy; combine with a heuristic (output length, tool calls, hedging words).

Pattern 3 — Sub-agent Delegation (Opus orchestrates, Haiku workers)

Orchestrator reasons about the plan, workers execute atomic steps:

Opus (planner)
  ├── Haiku (extract_dates_from_doc_1)
  ├── Haiku (extract_dates_from_doc_2)
  ├── Haiku (extract_dates_from_doc_3)
  └── Opus (synthesize all extractions into timeline)

Real example: /orchestrate in ai-toolkit runs Opus as planner, subagents (model per agent's frontmatter) as workers. See app/agents/*.md — each agent sets model: explicitly.

Pattern 4 — Fallback Chain (resilience, not cost)

When primary is rate-limited or errors, degrade gracefully:

def call_with_fallback(messages):
    for model in ["claude-opus-4-8", "claude-sonnet-5", "claude-haiku-4-5"]:
        try:
            return client.messages.create(model=model, messages=messages, ...)
        except (RateLimitError, OverloadedError):
            continue
    raise AllModelsExhausted()

Useful in production, not for cost optimization — you lose quality on fallback.

Pattern 5 — Task-Specific Routing

Skip generic complexity scoring when you know the task type:

Task	Route
Commit message from diff	Haiku
Summarize 5-10 lines	Haiku
Classify intent	Haiku
Fix a failing test	Sonnet
Write new feature	Sonnet
Code review, architecture decision	Opus
Multi-agent orchestration	Opus
Complex debugging across systems	Opus

Encode this as a map in code, not a prompt.

Anti-patterns

Anti-pattern	Consequence	Fix
Opus for everything	10-40x bill	Start with Sonnet, measure, demote
Haiku for code review	Misses subtle bugs	Sonnet minimum for code quality
Router overhead > savings	Haiku classifier eats the margin	Skip router if >80% of traffic is one tier
Different prompts per tier	Maintenance nightmare	Same prompt, just swap model
No telemetry	Can't optimize	Log model + tokens + cost per request

Measuring

Track per-route:

• Cost per request
• Latency p50/p95
• Quality score (human-labeled or auto-evaluated)
• Escalation rate (how often you fell back to a bigger model)

Target: move the Pareto curve — cheaper at equal quality OR better at equal cost.

Related

• llm-ops-engineer agent — production routing strategy
• prompt-caching-patterns — stack caching on top of routing
• json-mode-patterns — structured confidence from Haiku
• Anthropic cookbook: https://github.com/anthropics/claude-cookbooks — see "sub-agents" notebook