Model Selection in the Claude Agent SDK

The three tiers of Anthropic models

Every agent you build runs on a model. Picking the right one affects cost, speed, and quality. Anthropic's model lineup has three clear tiers:

Pass the model name to your query options:

for await (const message of query(messages(), {
  model: "claude-haiku-4-5",  // or claude-sonnet-4-5, etc.
  permissionMode: "bypassPermissions",
  dangerouslyAllowBypassPermissions: true,
})) {
  // handle messages
}

Sonnet 4.5 is the default fallback model if you set a fallback and your primary model fails. If you do not set a fallback, the SDK will use Sonnet 4.5 automatically in failure scenarios.

The development vs production model pattern

Run Haiku during development. You are testing structure, not quality. The agent behavior you care about — tool calls working correctly, session resumption functioning, hooks firing — is independent of which model you use.

Switch to Sonnet or Opus when:

• You are testing the quality of the agent's responses against your actual use case
• The task requires complex multi-step reasoning
• You are running a final check before deploying to users

This saves meaningful money during iteration cycles, especially if you are running many test sessions per day.

Setting a fallback model

A fallback model activates when the primary model hits its budget limit or becomes temporarily unavailable:

for await (const message of query(messages(), {
  model: "claude-opus-4-5",
  fallbackModel: "claude-sonnet-4-5",
  maxBudgetUsd: 2.0,
  permissionMode: "bypassPermissions",
  dangerouslyAllowBypassPermissions: true,
})) {
  // handle messages
}

If the session hits $2 while running Opus, the SDK switches to Sonnet and continues. The session does not fail.

This matters most for long-running agents that might hit budget caps mid-task. Without a fallback, the session terminates. With one, the agent degrades gracefully.

Switching models mid-session with hooks

You can change models during a session based on what the agent is doing. A hook that detects a specific tool being called can trigger a model switch.

The implementation details are covered in the hooks guide, but the pattern is: use a cheaper model for routine tool calls, escalate to a more capable model when the agent hits a reasoning-heavy decision point.

This is a more advanced pattern and not necessary for most deployments. Worth knowing it exists before you build a workflow where model escalation would make sense — for example, an agent that uses Haiku for web searches and Opus to synthesize the findings into a board-ready summary.

> Operator default: Sonnet for production agents handles the vast majority of real-world operator tasks. Research, report drafting, meeting prep, competitive analysis — Sonnet handles all of it. Reserve Opus for tasks where the quality difference is visible and valuable to the client. Haiku stays in the development loop and in any high-volume automation where cost per call adds up.

---

Author: FractionalSkill