Advisor Tool, Opus as advisor and Sonnet as executor in one API call

Anthropic released the Advisor Strategy on April 9, 2026. It is not a new model and not a new API. It is a tool type that you drop into a perfectly ordinary Messages API request. The effect: your executor model, say Sonnet 5 or Haiku 4.5, drives the task end-to-end and only calls a stronger advisor model when it runs into a wall. All in a single API call.

If you have been thinking about building multi-model routing yourself, don't. Anthropic took it off your hands. Here is how it works and when it pays off for you.

1. What the Advisor Strategy does

You give the model a perfectly ordinary Messages API request. In the tools you add an advisor entry. Sonnet or Haiku as executor reads the user prompt and works on it. The tool description is written so the model itself decides when the advisor would make sense. For 80 percent of the subtasks Sonnet notices that it has things under control and keeps working. For the 20 percent where it gets hairy, it calls the advisor.

What happens during the advisor call is transparent to you. Anthropic runs a separate inference pass server-side on the advisor model you name in the tool entry. The advisor reads the full conversation context, sends back a short piece of advice (typically 400 to 700 output tokens), and the executor carries on with it. The whole round-trip thing looks like a normal tool call in your API response, except you don't have to feed the result back yourself. The server holds the loop for you.

2. Required prerequisites

You need three things before this works.

First: the beta header anthropic-beta: advisor-tool-2026-03-01. Without the header the API returns an error. In the Anthropic SDK the header is the betas=["advisor-tool-2026-03-01"] parameter in the client.beta.messages.create call. As of August 9, 2026 the beta is still not GA, so when you move to production watch the Anthropic release notes.

Second: you have to use client.beta.messages.create, not client.messages.create. The beta tool type lives on its own endpoint path.

Third: executor and advisor have to form a valid pair. The rule behind it is simpler than the table: the advisor must be at least Sonnet 4.6, and at least as capable as the executor. Models of equal capability may advise each other. Haiku 4.5, Sonnet 4.6, Sonnet 5 and the Opus line up to Opus 5 are allowed as executors, and anything from Sonnet 4.6 up to Mythos 5 as advisor. Economically it still only pays off with a cheaper executor, because if you run Opus as the executor you are paying Opus prices anyway. The binding pair table lives in the Anthropic docs and shifts with every model generation, so don't pin it in your code.

3. Minimal example in Python

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-4-7",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Bau einen Worker-Pool in Go mit graceful shutdown.",
        }
    ],
)

print(response)

The tool block has only three fields: type is fixed at advisor_20260301, name is your label for the tool call (advisor is the convention), model is which advisor model gets consulted. Right now only claude-opus-4-7 makes sense. Other values are technically allowed, but the point of the strategy is Opus consultation.

For the multi-turn conversation pattern you append response.content (including any advisor_tool_result blocks) to the messages list, add the next user message, and call the API again. The advisor context is maintained cumulatively.

4. When the advisor pays off

The rule of thumb: long agentic tasks with a few tricky decision points. Code generation across 10+ files where only 2 or 3 spots really need architecture brain. Research synthesis over long documents where the executor only needs a hard judgment call at the endpoint. Multi-tool workflows where tool routing is mostly trivial but needs deep reasoning at the branches.

Not worth it for short, one-off requests. If you only have a 1-turn call anyway, take Opus directly or Sonnet directly, depending on what you need. The advisor probably won't get called on a single-turn call, because Sonnet doesn't find a wall where it needs it.

Also not worth it if you have Sonnet quality problems that show up in every sub-step. Then Sonnet is the wrong tool, and no advisor call saves you. Check beforehand whether Sonnet-solo really can't hold your quality bar.

5. Cost model and spend controls

The trick here is that you pay almost Sonnet prices but get Opus quality for the critical points. The executor produces most of the output tokens (at Sonnet prices, that is $3 per million output or $0.75 for Haiku). The advisor produces typically 400 to 700 output tokens per consultation (at Opus prices, $25 per million output).

In practice: with an 8000-token generation and three advisor consultations we are talking about roughly 6500 Sonnet tokens and 1500 Opus tokens. That is roughly 2 cents instead of 20 cents. A factor of 10 in savings at near-Opus quality.

What you should watch out for: the model decides about advisor calls on its own. If Sonnet gets over-cautious and calls the advisor at every sub-step, that eats up the cost advantage. Anthropic observed this in the beta and applies an implicit cap (I could not verify the exact number in the docs, but in practice you rarely see more than 5 advisor calls per generation). Log your calls in the first few weeks, look at the frequency, and adjust the user prompt if the executor consults too often.

6. Three concrete use cases that hit hard

Code generation with architecture points. You give Sonnet a 5-file refactoring job. Sonnet does the bulk of the work. At two spots that involve concurrency patterns or schema design, it calls Opus. Result: 80 percent of the tokens at Sonnet cost, critical architecture decisions with Opus reasoning.

Long-form document synthesis. You analyze 30 research papers, Sonnet does the reading and summarizing, Opus is consulted only for the final synthesis step where contradictions have to be resolved. On a 50k-token synthesis job that saves around 35 USD per run.

Customer support bot with escalation path. Haiku 4.5 as executor answers standard questions. For tricky cases (refund policy, edge-case bug) it consults Opus instead of escalating to human support. Saves human time and delivers better answers than Haiku-solo.

7. What the beta can't do

As advisor you can only configure Claude models from Sonnet 4.6 upwards. Your own fine-tunes or third-party models are not possible here, build that in your own logic if you need it.

One detail people trip over in practice: as soon as Opus 5, Fable 5 or Mythos 5 is the advisor, the result comes back as advisor_redacted_result, meaning encrypted. The executor reads it server-side, you do not see the advice in plaintext in your response. If you want to see what the advisor actually said while debugging, use claude-opus-4-8 as the advisor for that test run, which returns the plaintext advisor_result variant.

You don't see which sub-prompt the executor sends to the advisor. That is Anthropic-internal routing. If you need the exact advisor prompt for audit logs, that is currently not exposed. Workaround: in your system prompt, instruct the executor to briefly write down beforehand why it makes each advisor call.

Cross-region setups with Bedrock or Vertex are still in pilot phase in April 2026. If you run on AWS/GCP, check before rollout whether the beta is active on your region endpoint. Self-serve on platform.claude.com works everywhere right away.

8. Migration path for your existing code

If you already have a multi-model setup today (manual routing between Sonnet and Opus), you can move it to advisor step by step.

Step 1: pick out a small workflow where you run Opus today because Sonnet sometimes fails at one spot. Replace Opus with Sonnet plus the advisor tool. Log the frequency of the advisor calls.

Step 2: compare quality vs. solo Opus. For most workloads advisor-with-Sonnet is 95 percent as good as Opus-solo, at 10 percent of the cost. If quality doesn't hold, switch back.

Step 3: roll out to more workflows. Cost tracking over 2 to 4 weeks, then decide whether you run advisor-for-everything as the standard pattern or selectively.

9. The two pitfalls

Wrong beta format. The header is anthropic-beta: advisor-tool-2026-03-01, not advisor-2026-03-01 and not advisor-tool-2026-04-09. Anthropic beta headers are named after the beta tool type schema, the tool type is advisor_20260301. The date in the header is the schema date, not the release date.

Wrong API endpoint. Beta tools run through client.beta.messages.create, not client.messages.create. If you take the wrong endpoint, you get an unknown_beta error and no advisor function.

10. What comes next

My tip: don't switch all workflows at once. Pick out a multi-file code-generation job, run it 3 to 5 times with advisor, compare the output quality with your current Sonnet-only or Opus-only baseline. If the comparison checks out, roll out to other workflows.

If you want to go deeper into the cost optimization part, look at the playbook claude-code-cost-controls-für-daily-driver for the more comprehensive setup of token budgets and spend limits.

If you work with multi-agent setups and want to build advisor into your CEO-worker architecture, the step to lesson L5-04 on multi-agent patterns and L5-05 human-in-the-loop is worth it. Advisor is basically an automated human-in-the-loop, where the human is another LLM.

Sources

Specs verified against the official Anthropic documentation on 2026-05-07:

• platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool (tool schema, beta header, Python example, multi-turn pattern)
• platform.claude.com/docs/en/release-notes/overview (public beta since April 9, 2026, cost model description)

Secondary sources consulted:

• buildfastwithai.com Anthropic Advisor Strategy Guide (2026-04, cost comparison examples)
• testingcatalog.com Anthropic Advisor Tool Coverage (2026-04-09, release report)

Recipes consulted in the Academy:

• Phase 5 Multi-Agent Workflows
• Lesson L5-05 Human-in-the-Loop (analogous pattern at the human level)