Il tool advisor: Sonnet lavora, Fable pensa

Intermedio

Anthropic ha rilasciato una primitiva silenziosa ma di grande impatto in beta: il tool advisor. Un modello executor veloce (Sonnet, Haiku) guida il turno; nei punti di decisione passa il transcript completo a un advisor più forte (Opus 5, Fable 5, Mythos 5), l'advisor restituisce un piano, e l'executor continua a scrivere. Tutto lato server, in una sola chiamata /v1/messages — nessun round trip extra da parte tua.

Se stavi già alternando modelli a mano — Opus per pianificare, Sonnet per scrivere il codice — l'advisor collassa questa danza in una singola richiesta. È anche il primo pattern mainstream di produzione in cui vieni fatturato regolarmente su due tier di modello dentro una sola response, cosa che rompe ogni cost-tracker ingenuo scritto prima di marzo 2026 basato su usage.output_tokens * price.

What you'll learn

• Inviare una richiesta con l'header beta advisor-tool-2026-03-01, un modello executor e la definizione del tool advisor
• Leggere correttamente usage.iterations — output_tokens al top-level è solo dell'executor; i token dell'advisor stanno dentro le entry di tipo advisor_message nell'array iterations
• Scegliere la coppia executor/advisor — l'advisor deve essere almeno capace quanto l'executor, e Opus 5 / Fable 5 / Mythos 5 restituiscono contenuto cifrato che devi rispedire verbatim
• Limitare i consigli fuori controllo con max_tokens sulla definizione del tool (minimo 1024) — il max_tokens top-level NON limita l'advisor
• Abilitare il caching lato advisor per conversazioni con 3+ chiamate all'advisor, e sapere perché il valore di default di clear_thinking uccide silenziosamente quella cache
• Attivare /advisor in Claude Code con un advisorModel salvato — inclusa la gotcha del rollout di Fable 5 (attualmente disabilitato come advisor anche per organizzazioni con accesso a Fable)

Ultima verifica: 2026-08-04.

Verificato contro la documentazione ufficiale del tool advisor di Anthropic (platform + Claude Code) il 4 agosto 2026. L'advisor è in beta — gli abbinamenti dei modelli, il comportamento della cifratura, il rollout con Fable 5 disabilitato come advisor e la lista di piattaforme disponibili (solo Anthropic API + Claude Platform su AWS) sono i pezzi più a rischio di cambiare. Ricontrolla la fonte prima di fissare il comportamento in produzione.

Conferma confrontando con la fonte ufficiale.

Perché esiste l'advisor (e perché non è "chiamare due API")

L'alternativa ingenua è ovvia: chiami Opus, ottieni un piano, poi chiami Sonnet con il piano come system prompt. La documentazione di Anthropic è netta sul perché l'advisor batte questo approccio:

1. L'advisor legge il transcript completo dell'executor — ogni turno precedente, ogni tool call, ogni risultato, più il testo che l'executor ha prodotto finora nel turno corrente. Dovresti serializzare e inoltrare tutto a mano.
2. Gira dentro una sola richiesta /v1/messages. La tua connessione in streaming si mette in pausa (con ping SSE keepalive ogni ~30s) e poi il blocco advisor_tool_result arriva formato completo in un singolo evento content_block_start — niente delta. L'output dell'executor riprende lo streaming subito dopo.
3. L'executor decide quando chiamare l'advisor. Non fissi tu "sempre pianificare prima". Claude tende a chiamarlo prima di impegnarsi su un approccio, quando lo stesso errore continua a ripresentarsi, e prima di dichiarare completato il task.

L'advisor gira sotto un suo system prompt fornito da Anthropic, senza tool, senza context management, e i suoi blocchi di thinking vengono strippati prima che il risultato torni indietro. Solo il testo del consiglio (o un blob cifrato) arriva all'executor.

Quick start — la richiesta advisor minima funzionante

Executor Sonnet 5 + advisor Fable 5 (Python)

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
  model="claude-sonnet-5",
  max_tokens=4096,
  betas=["advisor-tool-2026-03-01"],
  tools=[
      {
          "type": "advisor_20260301",
          "name": "advisor",
          "model": "claude-fable-5",
      }
  ],
  messages=[
      {
          "role": "user",
          "content": "Build a concurrent worker pool in Go with graceful shutdown.",
      }
  ],
)

print(response)

Tre cose da notare:

• La stringa type è "advisor_20260301" e il name deve essere "advisor". Entrambi enforced letteralmente.
• L'header betas=["advisor-tool-2026-03-01"] è il flag che apre il tool. Stessa stringa su cURL come -H "anthropic-beta: advisor-tool-2026-03-01".
• L'input sul blocco server_tool_use che l'executor emette è sempre vuoto. Non lo riempi mai. Il server costruisce la vista dell'advisor dal transcript automaticamente.

La regola di abbinamento (e la sorpresa su Fable 5)

L'advisor deve essere almeno capace quanto l'executor, e Anthropic classifica i modelli di pari capacità come advisor l'uno dell'altro (Opus 4.7 e Opus 4.8 possono fare da advisor reciprocamente, Sonnet 5 e Opus 4.6 anche). Ecco la matrice completa accettata sulla Claude API ad agosto 2026:

Executor	Advisor accettati
claude-haiku-4-5	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, Sonnet 4.6
claude-sonnet-4-6	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, Sonnet 4.6
claude-sonnet-5	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7, Sonnet 5
claude-opus-4-6	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5
claude-opus-4-7	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7
claude-opus-4-8	Mythos 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7
claude-opus-5	Mythos 5, Fable 5, Opus 5
claude-fable-5	Fable 5, Opus 5
claude-mythos-5	Mythos 5, Opus 5

Le coppie invalide restituiscono un 400 invalid_request_error che nomina la combinazione non supportata. E c'è una particolarità su Claude Code che vale la pena segnalare separatamente: Fable 5 è attualmente disabilitato come advisor in Claude Code per le organizzazioni che altrimenti hanno accesso a Fable 5, controllato da un rollout server-side. Il picker /advisor mostra una riga sbiadita Fable 5 (temporarily unavailable) e /advisor fable viene rifiutato. Questo non tocca la API, dove claude-fable-5 come advisor funziona oggi.

La trappola del conteggio token in cui cadono quasi tutti gli integratori

Questa è la cosa più sorprendente sull'advisor e il motivo per cui non dovresti spedire un'integrazione advisor senza prima riscrivere il tuo cost tracker.

Il usage.output_tokens top-level riflette solo i token dell'executor. I token dell'advisor non sono aggregati nei totali top-level perché vengono fatturati alle tariffe del modello advisor, che sono quasi sempre diverse. Per vedere il quadro completo devi leggere usage.iterations[], un array che Anthropic ha aggiunto apposta per questa feature:

{
  "usage": {
    "input_tokens": 412,
    "cache_read_input_tokens": 0,
    "output_tokens": 531,
    "iterations": [
      { "type": "message",         "input_tokens": 412,  "output_tokens": 89 },
      { "type": "advisor_message", "model": "claude-fable-5",
                                   "input_tokens": 823,  "output_tokens": 1612 },
      { "type": "message",         "input_tokens": 1348, "cache_read_input_tokens": 412,
                                   "output_tokens": 442 }
    ]
  }
}

Le iterazioni marcate advisor_message vengono fatturate alle tariffe dell'advisor; quelle marcate message alle tariffe dell'executor. Le regole di aggregazione per i campi top-level sono anche asimmetriche — output_tokens top-level somma tutte le iterazioni executor, ma input_tokens e cache_read_input_tokens top-level riflettono solo la prima iterazione executor (gli input delle iterazioni executor successive includono gli output token precedenti, quindi ri-sommarli farebbe doppio conteggio).

Watch out

• Se calcoli il costo come usage.input_tokens * exec_input_price + usage.output_tokens * exec_output_price, sottostimi silenziosamente di tutta la spesa dell'advisor — le chiamate advisor emettono tipicamente 1.400-1.800 token totali inclusi i thinking, a una tariffa per token sostanzialmente più alta.
• I token dell'advisor NON attingono da alcun task budget applicato all'executor. Se ti affidi a task_budget come tetto di spesa hard, l'advisor sta fuori da quel tetto.
• Il Priority Tier si applica per-modello. Un impegno Priority Tier sull'executor non si estende all'advisor. Le chiamate advisor girano in Priority Tier solo se la tua organizzazione ha anche un impegno sul modello advisor.

Limitare consigli fuori controllo — la gotcha di max_tokens

Il max_tokens top-level limita solo l'output dell'executor. Per capare l'output totale dell'advisor per chiamata (thinking + testo), imposta max_tokens sulla definizione del tool:

Limitare l'advisor a 2048 token per chiamata

tools = [
  {
      "type": "advisor_20260301",
      "name": "advisor",
      "model": "claude-fable-5",
      "max_tokens": 2048,   # minimum is 1024; setting above the advisor's own output cap returns 400
      "max_uses": 5         # optional per-request cap; extra calls return error_code max_uses_exceeded
  }
]

Il benchmark hard-reasoning di Anthropic (n=40 per configurazione) riporta questi numeri come punti di partenza pratici:

max_tokens sul tool	Output medio advisor	Chiamate troncate
Non impostato	~10k+ token su task difficili	0%
2048 (consigliato)	~7 volte più piccolo del non impostato	~0%
1024 (minimo)	~10 volte più piccolo del non impostato	~10%

Le differenze di accuratezza tra le tre configurazioni erano dentro il rumore a quella dimensione del campione. Quando l'advisor tocca il tetto, il blocco risultato porta stop_reason: "max_tokens" e Anthropic appende [Advisor output truncated at max_tokens=2048.] (nominando il tuo tetto effettivo) al testo del consiglio così l'executor vede il troncamento nel suo contesto. Entrambi i segnali appaiono solo quando imposti max_tokens sulla definizione del tool — omettilo e non ottieni nessuno dei due.

Il layer di prompt caching che tutti si perdono

Ci sono due layer di caching indipendenti attorno all'advisor, e sbagliare uno dei due è una regressione di costo silenziosa.

Guided walkthrough1 of 3

1. Il blocco advisor_tool_result è cacheable come ogni altro content block. Un breakpoint cache_control piazzato dopo di esso in un turno successivo fa hit normalmente. Il prompt dell'executor contiene sempre il consiglio in chiaro indipendentemente dal fatto che il tuo client abbia ricevuto text o encrypted_content, quindi il comportamento di caching è identico per entrambe le varianti del risultato.

Anche attivare/disattivare caching a metà conversazione invalida la cache. Impostalo una volta, lascialo lì.

Le due varianti di risultato e perché sono entrambe ok

Le chiamate advisor riuscite restituiscono una di due forme di content:

• advisor_result con un campo text — consiglio leggibile dall'uomo. Restituito da Claude Opus 4.8 e dagli altri advisor non della generazione Opus 5.
• advisor_redacted_result con un campo encrypted_content — un blob opaco che non puoi leggere. Restituito dagli advisor Claude Opus 5, Claude Fable 5 e Claude Mythos 5.

Rispedisci quello che ricevi verbatim nei turni successivi. Al turno successivo, il server decifra il blob e rende il testo in chiaro nel prompt dell'executor — l'executor vede lo stesso contenuto in entrambi i casi. Se cambi advisor a metà conversazione, fai branch su content.type per gestire entrambe le forme.

Pro tip

• La variante redacted non è una limitazione — è il meccanismo che permette a Opus 5 / Fable 5 / Mythos 5 di emettere consigli su cui l'executor può agire senza esporre il ragionamento interno al tuo client. Se ti serve il testo del consiglio a livello di logging, usa Opus 4.8 come advisor.
• Entrambe le varianti portano uno stop_reason quando imposti max_tokens sulla definizione del tool, e lo omettono quando non lo imposti. Usalo per rilevare il troncamento senza parsare la stringa appesa.

Multi-turno: il 400 invisibile che colpirai esattamente una volta

Se ometti il tool advisor da tools in un turno successivo mentre la storia dei messaggi contiene ancora blocchi advisor_tool_result, la API restituisce 400 invalid_request_error. Due conseguenze:

1. Lo stato advisor è sticky. Una volta che un turno ha usato l'advisor, i turni successivi in quella conversazione devono tenere il tool in tools OPPURE strippare i blocchi advisor result dalla history. Non c'è un cap built-in a livello di conversazione.
2. Per imporre un budget client-side per-conversazione, conta le chiamate advisor da solo. Quando raggiungi il tuo tetto, rimuovi il tool advisor da tools e cancella ogni blocco advisor_tool_result dalla history dei messaggi nella stessa richiesta.

C'è anche una danza per riprendere un turno in pausa che vale la pena nominare così non fai cargo-cult: una response può finire con stop_reason: "pause_turn" mentre una chiamata advisor è ancora pending (la response contiene il blocco server_tool_use ma non ancora advisor_tool_result). Per riprendere, appendi quel messaggio assistant a messages invariato, tenendo il blocco server_tool_use, e ri-invia con lo stesso tool advisor + beta header. Nessun messaggio utente, nessun tool_result. La API esegue la chiamata advisor pending e continua il turno dell'executor. Un turno ripreso può mettersi di nuovo in pausa — ripeti.

Codici errore da ignorare vs da far emergere

Il fallimento della sub-chiamata advisor non fa fallire la richiesta. L'executor vede l'errore e continua senza ulteriori consigli. Tabella errori completa:

error_code	Significato	Risposta pratica
max_uses_exceeded	Hai raggiunto il cap max_uses per-request	Atteso — l'hai configurato tu. Loggalo a livello debug.
too_many_requests	Sub-inference advisor rate-limitata (dallo stesso bucket per-modello delle chiamate dirette)	Alerta se succede ripetutamente — stai saturando il tuo rate limit sul modello advisor
overloaded	Sub-inference advisor a capacità	Ritenta l'intero turno se la qualità conta; altrimenti lasciala passare
prompt_too_long	Il transcript ha superato la context window dell'advisor	Raro con advisor Opus 5 da 1M di contesto; più probabile con scelte advisor a contesto minore
execution_time_exceeded	Sub-inference advisor in timeout	Limita max_tokens sulla definizione del tool per ridurre la lunghezza di generazione dell'advisor
unavailable	Qualsiasi altra cosa	Trattala come transiente

L'asimmetria critica: un rate limit sull'executor fa fallire l'intera richiesta con HTTP 429. Un rate limit sull'advisor appare dentro il risultato del tool e la richiesta ha comunque successo.

Claude Code: /advisor, --advisor e advisorModel

La CLI espone l'advisor attraverso tre superfici che impostano tutte la stessa impostazione:

Abilitare l'advisor in Claude Code — tre modi equivalenti

# 1. Interactive picker or direct assignment (saves to your user settings)
/advisor
/advisor opus
/advisor sonnet
/advisor claude-opus-5   # full model ID also works

# 2. Persistent default in your settings file
# ~/.config/claude/settings.json (or equivalent)
{ "advisorModel": "opus" }

# 3. Per-session flag (overrides advisorModel for that launch, hidden from --help)
claude --advisor opus

# Turn off
/advisor off
# Or disable the tool entirely (all three surfaces become no-ops):
export CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1

La matrice di abbinamento main-model / advisor in Claude Code è un sottoinsieme di quella della API — opus e sonnet sono alias che risolvono alla versione di default built-in di Claude Code e avanzano con le release. Regole notevoli:

• I main Opus 4.7+ accettano solo Opus 4.7 o successivo come advisor — un main Opus 4.7 con un advisor Opus 4.6 o Sonnet 5 viene rifiutato.
• Il main Sonnet 5 rifiuta Sonnet 4.6 come advisor — ma accetta Sonnet 5 (un "secondo Sonnet che legge il primo" per un check indipendente a basso costo).
• I subagent ereditano l'advisor configurato e applicano lo stesso check di abbinamento contro il proprio modello.
• Abilitare o disabilitare l'advisor a metà sessione NON invalida la prompt cache del main model — a differenza del cambio di modello o di effort level, che sì. Per questo /advisor è sicuro da togglare a metà task.

Osserva il transcript per una riga Advising con il nome del modello advisor mentre la chiamata è in corso; premi Ctrl+O per espanderla e leggere la guida completa. Claude generalmente segue il consiglio ma si adatta quando la propria evidenza contraddice una specifica affermazione (uno step fallisce quando viene provato, il contenuto di un file contraddice il consiglio) — fa emergere il conflitto invece di seguire in modo incondizionato.

I due pattern di prompt di produzione che Anthropic usa davvero

La documentazione ufficiale include due system prompt che Anthropic ha testato su scala. Vale la pena copiarli, perché "l'advisor sa cosa fare" non è un default — l'executor ha bisogno di guida esplicita su quando chiamare l'advisor, e l'advisor beneficia di prompt scritti in seconda persona (vede il tuo system prompt come contesto quotato, quindi "tu sei..." atterra più affidabilmente di "l'executor è...").

System prompt suggerito per task di coding (executor Sonnet/Opus)

You have access to an advisor tool that consults a stronger model for
strategic guidance. Call it when the plan matters more than the code:

- Before committing to an approach on a non-trivial task.
- When stuck — errors recurring, approach not converging, results that
don't fit.
- Before declaring the task complete, to independently check the work.

Do NOT call it for routine turns where the next step is obvious. The
advisor sees the full transcript, so state the specific decision you
want reviewed in the turn where you invoke it.

Per l'executor Haiku, Anthropic fornisce una variante leggermente spinta che incoraggia più chiamate all'advisor (Haiku consulta troppo poco di default):

System prompt alternativo per executor Haiku

You have access to an advisor tool. Consult it whenever a decision
requires judgment beyond mechanical execution:

- Before committing to a non-trivial approach.
- When stuck -- errors recurring, approach not converging, results that
don't fit.
- Before declaring the task complete.
- When the user's request contains ambiguity you cannot resolve from
context.

Bias toward calling the advisor rather than guessing. The cost of a
consult is small compared to the cost of a wrong direction on a long
task.

Per tagliare la lunghezza dell'output advisor via prompting (alternativa o complemento a max_tokens sul tool), il posizionamento testato di Anthropic è una riga nel messaggio utente — non nel system prompt — perché l'advisor vede entrambi quotati, ma le istruzioni nel messaggio utente che gli si rivolgono direttamente vengono seguite più affidabilmente dei system prompt in terza persona. Esempio: Advisor: keep guidance to 3-5 sentences.

Per forzare una consulta su una richiesta specifica, imposta tool_choice a {"type": "tool", "name": "advisor"}. Un'incompatibilità: l'uso forzato del tool non può essere combinato con extended thinking manuale (thinking: {type: "enabled"}) — la API restituisce 400 invalid_request_error se abiliti entrambi. Adaptive thinking supporta l'uso forzato del tool.

Dove l'advisor batte — e perde contro — le sue alternative

Hai quattro modi per combinare le forze dei modelli in Claude Code. Scegli in base a quando vuoi che il modello più forte giri.

Approccio	Il modello più forte gira	Avviato da
Tool advisor	Nei punti di decisione, a metà task	Claude lo chiama quando serve guida
opusplan	Durante il plan mode, poi passa a Sonnet per l'esecuzione	Tu entri in plan mode
Subagent con model impostato	Per l'intero sub-task delegato	Claude delega, o lo invochi tu
Switch /model	Per tutti i turni successivi	Tu cambi modello a mano

L'advisor è l'unico che fa girare il modello forte a discrezione di Claude, on demand. opusplan è deterministico (ingresso in plan mode) ma limitato alla pianificazione. I subagent impegnano il modello forte per un intero sub-task. /model è la mazzata.

Disponibilità di piattaforma (quella su cui inciamperai)

Il tool advisor è disponibile in beta sulla Anthropic API e Claude Platform su AWS. Non è disponibile su Amazon Bedrock, Google Cloud Vertex o Microsoft Foundry ad agosto 2026. Attraverso un LLM gateway configurato con ANTHROPIC_BASE_URL, la disponibilità dipende dal fatto che il gateway inoltri la richiesta intatta.

Se sei multi-cloud e passi le richieste attraverso Bedrock o Vertex per sopravvivere a un'outage di Anthropic, l'advisor non fa parte di quel failover path oggi.

Check yourself

0/5

1. 1La tua richiesta executor Sonnet 5 + advisor Fable 5 restituisce una response con usage.output_tokens = 400. Quanto ha generato l'advisor?
2. 2Vuoi un tetto hard di 2048 token su ogni chiamata advisor. Dove imposti max_tokens?
3. 3Configuri claude-opus-4-7 come executor e claude-sonnet-5 come advisor. Cosa succede?
4. 4Il tuo advisor Claude Fable 5 restituisce content di tipo advisor_redacted_result con un campo encrypted_content. Cosa fai al turno successivo?
5. 5Vuoi rimuovere il tool advisor dal tuo array `tools` in un turno successivo per imporre un tetto di costo client-side. Cos'altro devi fare?

Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.

1 / 9

Fonti e approfondimenti

• Anthropic — Advisor tool (documentazione Claude API) — la fonte primaria; reference dei campi, matrice di abbinamento, comportamento di streaming e i prompt testati da Anthropic e i benchmark di troncamento citati in questa pagina
• Anthropic — Escalate hard decisions with the advisor tool (documentazione Claude Code) — la superficie specifica della CLI: /advisor, advisorModel, --advisor, il rollout con Fable-5-disabilitato-come-advisor, e il sottoinsieme di abbinamento
• Anthropic — Server tools reference — la forma del blocco server_tool_use e il comportamento "mescolare server tool e client tool in un turno" che l'advisor eredita
• Anthropic — Prompt caching — semantiche di cache che si applicano sia al blocco advisor_tool_result lato executor sia all'opt-in caching lato advisor
• Anthropic — Context editing — il default di clear_thinking che uccide silenziosamente il caching lato advisor sugli executor più vecchi
• AILmanac — Effort tuning: 5 livelli, default per modello e la cache trap — la feature gemella che si accoppia con l'advisor; entrambe sono manopole di superficie per-modello che cambiano il conteggio token
• AILmanac — Scegliere un modello — i tier di modello che determinano quali coppie executor/advisor sono legali
• Anthropic Blog — La strategia advisor — la framing "perché un executor veloce con un advisor più forte funziona" dal blog di Anthropic