Advisor tool: pairing a fast executor with Opus-level judgment

The Advisor tool is an API beta feature that pairs two Claude models in a single agent workflow: a fast executor (typically Sonnet or Haiku) handles most of the work, while a separate Opus instance acts as an advisor called only when complex decisions arise. The result is an agent with near-executor speed and near-Opus judgment.

The architecture

Standard agentic workflows face a tradeoff: powerful models (Opus) produce better judgment but are slower and more expensive. Fast models (Sonnet, Haiku) handle routine steps efficiently but can miss nuance on complex decisions.

The Advisor tool resolves this. Most of the time, the executor model runs. When the executor encounters a decision point that warrants deeper analysis — an ambiguous requirement, a risky action, a multi-path problem — it invokes the advisor. Opus evaluates the situation and returns guidance. The executor continues with that guidance.

In practice, most agent steps are routine: read a file, call an API, parse a response. The few steps that require real judgment — "should I delete this file?", "which of these three approaches fits the architecture?" — are where Opus input actually matters. The Advisor tool pays for Opus reasoning only on those steps.

API setup

The Advisor tool requires the anthropic-beta: advisor-tool-2026-03-01 header:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    extra_headers={"anthropic-beta": "advisor-tool-2026-03-01"},
    tools=[{"type": "advisor", "name": "advisor"}],
    messages=[{"role": "user", "content": "Your task here"}]
)

The executor model (specified in model) calls the advisor tool when it needs guidance. Advisor responses come from Opus automatically — you do not configure which model to use as the advisor.

When it is worth using

The Advisor tool is most valuable for long-running agents with a mix of routine and complex decisions. If your agent mostly does simple sequential tasks, the overhead of the advisor pattern is not worth it. If your agent hits genuine decision points — where the right path depends on context, judgment, or tradeoffs — the Advisor tool makes those moments more reliable without slowing down the whole workflow.

It is also a useful pattern for reducing costs on Opus-heavy workflows: if you currently run everything on Opus for safety, the Advisor tool lets you shift most execution to Sonnet while preserving Opus judgment where it matters.

Further reading

• Advisor tool documentation — full API reference and configuration options
• The Advisor Strategy — Anthropic's explanation of the design philosophy and when to apply it
• Building effective agents — the broader framework for designing multi-step agent workflows
• Managed Agents overview — Anthropic's broader agent infrastructure and patterns