Strumento advisor

Lo strumento advisor consente a un modello executor più veloce e a costo inferiore di consultare un modello advisor di intelligenza superiore durante la generazione per ottenere guida strategica. L'advisor legge l'intera conversazione, produce un piano o una correzione di rotta, e l'executor continua con il compito.

Questo pattern si adatta a carichi di lavoro agentici a lungo orizzonte (agenti di coding, computer use, pipeline di ricerca multistep) in cui la maggior parte dei turni è meccanica ma avere un piano eccellente è cruciale. Ottieni una qualità vicina a quella dell'advisor da solo mentre la maggior parte della generazione di token avviene alle tariffe del modello executor.



Quando usarlo

L'advisor si adatta a queste configurazioni:

• Attualmente usi Sonnet su compiti complessi: Aggiungi un advisor di livello superiore. Opus mantiene il costo totale simile o inferiore; Claude Fable 5 massimizza il miglioramento di qualità.
• Attualmente usi Haiku e vuoi un salto di intelligenza: Aggiungi un advisor Opus o Fable. Aspettati un costo più alto rispetto a Haiku da solo, ma inferiore rispetto a passare l'executor a un modello più grande.

I risultati dipendono dal compito. Valuta sul tuo carico di lavoro.

L'advisor è meno adatto per Q&A a turno singolo (niente da pianificare), selettori di modelli puramente pass-through in cui i tuoi utenti scelgono già il proprio compromesso tra costo e qualità, o carichi di lavoro in cui ogni turno richiede genuinamente la piena capacità del modello advisor.



Avvio rapido

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-opus-5",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown.",
        }
    ],
)

print(response)

Il content della risposta include un blocco advisor_tool_result che contiene la guida dell'advisor. Con Claude Opus 5, Claude Fable 5 o Claude Mythos 5 come advisor, il campo content del blocco è una variante advisor_redacted_result (crittografata; l'executor la legge lato server, ma il tuo client no). Per vedere il testo del consiglio direttamente nella tua risposta, usa invece claude-opus-4-8 come modello advisor, che restituisce la variante advisor_result in testo semplice. Consulta Varianti del risultato per entrambe le forme e Compatibilità dei modelli per l'elenco completo delle coppie valide.



Come funziona

Quando aggiungi lo strumento advisor al tuo array tools, il modello executor determina quando chiamarlo, come qualsiasi altro strumento. Quando l'executor chiama l'advisor:

1. L'executor emette un blocco server_tool_use con name: "advisor" e un input vuoto. L'executor segnala il momento, e il server fornisce il contesto.
2. Anthropic esegue un passaggio di inferenza separato sul modello advisor lato server. L'advisor viene eseguito con il proprio prompt di sistema fornito da Anthropic e riceve la trascrizione completa dell'executor come contesto citato nel suo input. Quella trascrizione include il tuo prompt di sistema, le definizioni degli strumenti, i turni precedenti e i risultati degli strumenti, e il testo che l'executor ha prodotto finora in questo turno.
3. La risposta dell'advisor ritorna all'executor come blocco advisor_tool_result.
4. L'executor continua a generare, informato dal consiglio.

Tutto questo avviene all'interno di una singola richiesta /v1/messages, senza round trip aggiuntivi dal tuo lato. L'eccezione è un turno che si mette in pausa a metà chiamata, che riprendi con una richiesta successiva (consulta Riprendere un turno in pausa).

L'advisor stesso viene eseguito senza strumenti e senza gestione del contesto. I suoi blocchi di pensiero vengono eliminati prima che il risultato ritorni. Solo il testo del consiglio raggiunge l'executor.



Parametri dello strumento

L'oggetto caching ha la forma {"type": "ephemeral", "ttl": "5m" | "1h"}. A differenza di cache_control sui blocchi di contenuto, questo non è un marcatore di breakpoint. È un interruttore on/off. Il server determina dove vanno i confini della cache.

Lo strumento advisor accetta anche le proprietà generiche disponibili su qualsiasi definizione di strumento: cache_control, allowed_callers, defer_loading e strict (trattate in output strutturati). Consulta il Riferimento degli strumenti per la loro semantica.



Struttura della risposta



Chiamata all'advisor riuscita

Quando l'advisor viene chiamato, un blocco server_tool_use è seguito da un blocco advisor_tool_result nel contenuto dell'assistente. L'esempio seguente mostra la variante advisor_result in testo semplice restituita da un advisor Claude Opus 4.8. L'Avvio rapido usa Claude Opus 5, che restituisce invece la variante crittografata advisor_redacted_result; consulta Varianti del risultato.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me consult the advisor on this."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "advisor",
      "input": {}
    },
    {
      "type": "advisor_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "advisor_result",
        "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
      }
    },
    {
      "type": "text",
      "text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..."
    }
  ]
}

Il server_tool_use.input è sempre vuoto. Il server costruisce automaticamente la vista dell'advisor dalla trascrizione completa. Nulla di ciò che l'executor inserisce in input raggiunge l'advisor.



Varianti del risultato

Il campo advisor_tool_result.content è una discriminated union. Per le chiamate riuscite, la variante dipende dal modello advisor:

Gli advisor Claude Opus 5, Claude Fable 5 e Claude Mythos 5 restituiscono advisor_redacted_result. Gli altri modelli advisor nella tabella di compatibilità restituiscono advisor_result.

Entrambe le varianti del risultato contengono un campo stop_reason quando imposti max_tokens sulla definizione dello strumento, e lo omettono quando non lo fai. Contiene lo stop reason della sub-chiamata dell'advisor, tipicamente "end_turn", o "max_tokens" quando il limite viene raggiunto. I valori corrispondono al stop_reason di primo livello della Messages API.

Con advisor_result, il campo text contiene consigli leggibili dall'utente. Con advisor_redacted_result, il campo encrypted_content contiene un blob opaco che non puoi leggere. Al turno successivo, il server lo decrittografa e renderizza il testo semplice nel prompt dell'executor.

In entrambi i casi, rinvia il contenuto invariato nei turni successivi. Se cambi modello advisor a metà conversazione, gestisci entrambe le forme in base a content.type.



Risultati di errore

Se la chiamata all'advisor fallisce, il risultato contiene un errore:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_tool_result_error",
    "error_code": "overloaded"
  }
}

L'executor vede l'errore e continua senza ulteriori consigli. La richiesta stessa non fallisce.

I limiti di velocità dell'advisor attingono dallo stesso bucket per modello delle chiamate dirette al modello advisor. Un limite di velocità sull'advisor appare come too_many_requests all'interno del risultato dello strumento. Un limite di velocità sull'executor fa fallire l'intera richiesta con HTTP 429.



Conversazioni multi-turno

Passa l'intero contenuto dell'assistente, inclusi i blocchi advisor_tool_result, all'API nei turni successivi. Questo esempio usa claude-opus-4-8 come advisor in modo che il consiglio in testo semplice sia visibile in response.content; la meccanica è identica per qualsiasi modello advisor.

client = anthropic.Anthropic()

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-8",
    }
]

messages = [
    {
        "role": "user",
        "content": "Build a concurrent worker pool in Go with graceful shutdown.",
    }
]

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Aggiungi l'intero contenuto della risposta, inclusi eventuali blocchi advisor_tool_result
messages.append({"role": "assistant", "content": response.content})

# Continua la conversazione
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

Puoi rimuovere lo strumento advisor da tools in un turno successivo mentre la cronologia dei messaggi contiene ancora blocchi advisor_tool_result. La richiesta viene accettata e i blocchi storici vengono preservati; il modello non può chiamare l'advisor in quel turno. Devi comunque inviare l'header beta advisor-tool-2026-03-01 affinché quei blocchi storici vengano accettati.



Riprendere un turno in pausa

Una risposta può terminare con stop_reason: "pause_turn" mentre una chiamata all'advisor è ancora in sospeso. Quando ciò accade, la risposta contiene il blocco server_tool_use dell'advisor senza un advisor_tool_result corrispondente. Per riprendere, aggiungi quel messaggio dell'assistente a messages con il suo contenuto invariato, mantenendo il blocco server_tool_use, e invia nuovamente la richiesta con lo stesso strumento advisor e header beta. Non è necessario aggiungere un messaggio utente o un blocco tool_result. L'API esegue la chiamata all'advisor in sospeso e continua il turno dell'executor nella nuova risposta. Un turno ripreso può mettersi nuovamente in pausa. In tal caso, ripeti lo stesso passaggio. Omettere lo strumento advisor dalla richiesta di ripresa restituisce un 400 invalid_request_error, perché il blocco server_tool_use in sospeso non ha una definizione di strumento su cui eseguire; includi lo strumento ogni volta che una chiamata è in sospeso. Se invece l'executor ha chiamato uno dei tuoi strumenti nello stesso turno, la risposta termina con stop_reason: "tool_use" mentre la chiamata all'advisor è ancora in sospeso. Invia i blocchi tool_result come di consueto, e la chiamata all'advisor in sospeso viene eseguita all'inizio di quella richiesta successiva. Consulta Combinare strumenti server e strumenti client in un unico turno.



Promemoria a metà conversazione per executor che chiamano troppo poco

Se un executor Haiku non ha chiamato l'advisor nel suo primo turno di assistente, aggiungi un breve promemoria come messaggio utente aggiuntivo prima del secondo turno di assistente. Nella valutazione comportamentale interna di Anthropic questo ha aumentato i tassi di successo dei compiti di circa 7 punti percentuali sugli executor Haiku. Sugli executor Sonnet, il promemoria in testo semplice non ha avuto effetti misurabili nei test di Anthropic. Le considerazioni sul timing delle chiamate che seguono sono particolarmente rilevanti per Sonnet. Non applicare il promemoria agli executor Opus: su Opus ha leggermente abbassato i tassi di successo.

Con il NUDGE_TURN predefinito di 2, il promemoria arriva tipicamente dopo che il modello si è orientato sul compito ma prima che si sia impegnato in un approccio.

client = anthropic.Anthropic()

NUDGE_TURN = 2  # inject before this assistant turn if no advisor call yet
NUDGE_TEXT = (
    "You have not consulted the advisor yet. If the task has a non-obvious "
    "design decision or a failure mode you haven't ruled out, call advisor "
    "now before committing to an approach."
)
MAX_TURNS = 10  # agent loop cap


def run_your_tools(content):
    # Sostituisci con il tuo dispatch degli strumenti. Restituisce un blocco tool_result per ogni blocco tool_use.
    return [
        {
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": "Replace with your tool output.",
        }
        for block in content
        if block.type == "tool_use"
    ]


tools = [
    {"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-5"},
    # ... gli altri tuoi strumenti
]
task = "Build a concurrent worker pool in Go with graceful shutdown."
messages = [{"role": "user", "content": task}]
advisor_called = False

for turn in range(1, MAX_TURNS + 1):
    response = client.beta.messages.create(
        model="claude-haiku-4-5",
        max_tokens=4096,
        betas=["advisor-tool-2026-03-01"],
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content})
    advisor_called = advisor_called or any(
        block.type == "server_tool_use" and block.name == "advisor"
        for block in response.content
    )
    if response.stop_reason == "end_turn":
        break
    if response.stop_reason == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it

    results = run_your_tools(response.content)  # list of tool_result blocks
    if results:
        messages.append({"role": "user", "content": results})
    # Salta questo se il tuo prompt di sistema dice già al modello di chiamare con parsimonia.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

Aggiungi il promemoria come messaggio utente separato dopo i risultati degli strumenti anziché come blocco fratello nello stesso messaggio. Messaggi utente consecutivi sono validi. Nei test di Anthropic sugli executor Haiku e Sonnet si sono comportati in modo equivalente a un blocco fratello. La forma a messaggio separato mantiene anche il promemoria chiaramente distinto dall'output degli strumenti.

Compromessi: Il promemoria aumenta il tasso di chiamata, il che può spingere compiti banalmente semplici verso una consultazione non necessaria. Se il tuo carico di lavoro mescola compiti semplici e complessi, considera di aumentare NUDGE_TURN a 3 in modo che i compiti a due turni si completino prima che il promemoria si attivi, oppure condiziona il promemoria a un segnale di complessità del compito che già calcoli. Se il tuo prompt di sistema contiene già linguaggio di moderazione ("riserva l'advisor per incertezza genuina"), salta completamente il promemoria, perché le due istruzioni sono in conflitto.

Il promemoria in testo semplice è altamente saliente sugli executor Haiku e Sonnet: dal 74 percento (Sonnet) al 98 percento (Haiku) dei tentativi con promemoria nei test di Anthropic ha chiamato l'advisor immediatamente al turno 2. Se ciò avviene prima che il tuo executor abbia letto il problema o raccolto contesto, la chiamata all'advisor risultante è a basso contesto e può sostituire una chiamata successiva meglio temporizzata. Misura il turno di prima chiamata baseline del tuo executor prima di aggiungere il promemoria. Se l'executor chiama già l'advisor in modo affidabile e la sua prima chiamata avviene tipicamente al turno N, imposta NUDGE_TURN maggiore di N. Nei test di Anthropic, un promemoria al turno 2 su carichi di lavoro in cui la prima chiamata baseline era al turno 7 o successivo è correlato a un calo di prestazioni del compito di 3-4 punti percentuali. Su un carico di lavoro di navigazione in cui il tasso di chiamata baseline era dell'86 percento, lo stesso promemoria ha aumentato l'engagement senza costi sulle prestazioni del compito.

Per forzare una consultazione su una richiesta specifica invece di usare il promemoria, imposta tool_choice su {"type": "tool", "name": "advisor"}, soggetto ai vincoli in Forzare l'uso degli strumenti. Forzare l'uso degli strumenti non può essere combinato con il pensiero esteso manuale (thinking: {type: "enabled"}): l'API restituisce un 400 invalid_request_error se abiliti entrambi. Il pensiero adattivo supporta l'uso forzato degli strumenti.



Streaming

La sub-inferenza dell'advisor non fa streaming. Lo stream dell'executor si mette in pausa mentre l'advisor è in esecuzione; poi il risultato completo arriva in un singolo evento.

Il blocco server_tool_use con name: "advisor" segnala che una chiamata all'advisor sta iniziando. La pausa inizia quando quel blocco si chiude (content_block_stop). Durante la pausa, lo stream è silenzioso tranne per i keepalive SSE ping standard emessi circa ogni 30 secondi. Chiamate brevi all'advisor potrebbero non mostrare ping.

Quando l'advisor termina, l'advisor_tool_result arriva completamente formato in un singolo evento content_block_start (nessun delta). L'output dell'executor riprende quindi lo streaming.

Segue un evento message_delta con l'array usage.iterations aggiornato che riflette i conteggi dei token dell'advisor.



Utilizzo e fatturazione

Le chiamate all'advisor vengono eseguite come sub-inferenza separata fatturata alle tariffe del modello advisor. L'utilizzo è riportato nell'array usage.iterations[]:

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

I campi usage di primo livello riflettono solo i token dell'executor. I token dell'advisor non vengono inclusi nei totali di primo livello perché sono fatturati a una tariffa diversa. Le iterazioni con type: "advisor_message" sono fatturate alle tariffe del modello advisor, e le iterazioni con type: "message" sono fatturate alle tariffe del modello executor.

Ogni campo usage di primo livello è la somma di quel campo su tutte le iterazioni dell'executor, inclusi input_tokens, output_tokens e cache_read_input_tokens. Poiché ogni iterazione dell'executor rinvia la conversazione crescente, gli input delle iterazioni successive includono l'output delle iterazioni precedenti, quindi la somma di input_tokens supera la dimensione di qualsiasi singolo prompt. Usa usage.iterations per una suddivisione completa per iterazione quando costruisci logica di tracciamento dei costi.

L'output dell'advisor è tipicamente da 400 a 700 token di testo, o da 1.400 a 1.800 token totali incluso il pensiero. Il risparmio sui costi deriva dal fatto che l'advisor non genera il tuo output finale completo. L'executor lo fa alla sua tariffa inferiore.

Il max_tokens di primo livello si applica solo all'output dell'executor. Non limita i token della sub-inferenza dell'advisor. Per limitare direttamente l'output dell'advisor, imposta max_tokens sulla definizione dello strumento. I token dell'advisor inoltre non attingono da alcun budget del compito applicato all'executor.

Il Priority Tier si applica a ciascun modello in modo indipendente. Un impegno Priority Tier sul modello executor non si estende all'advisor. Le chiamate all'advisor vengono eseguite al Priority Tier solo se la tua organizzazione detiene anche un impegno sul modello advisor.



Cache dei prompt dell'advisor

Ci sono due livelli di caching indipendenti.



Caching lato executor

Il blocco advisor_tool_result è memorizzabile in cache come qualsiasi altro blocco di contenuto. Un breakpoint cache_control posizionato dopo di esso in un turno successivo fa hit. Il prompt dell'executor contiene sempre il consiglio in testo semplice indipendentemente dal fatto che il tuo client abbia ricevuto text o encrypted_content, quindi il comportamento del caching è identico per entrambe le varianti del risultato.



Caching lato advisor

Imposta caching sulla definizione dello strumento per abilitare la cache dei prompt per la trascrizione dell'advisor tra le chiamate all'interno della stessa conversazione:

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
        "caching": {"type": "ephemeral", "ttl": "5m"},
    }
]

Il prompt dell'advisor alla N-esima chiamata è il prompt della (N-1)-esima chiamata con un segmento in più aggiunto, quindi il prefisso è stabile tra le chiamate. Con caching abilitato, ogni chiamata all'advisor scrive una voce di cache, e la chiamata successiva legge fino a quel punto e paga solo per il delta. Vedrai cache_read_input_tokens diventare diverso da zero sulla seconda e successive iterazioni advisor_message.

Quando abilitarlo: La scrittura in cache costa più di quanto le letture risparmino quando l'advisor viene chiamato due o meno volte per conversazione. Il caching raggiunge il pareggio a circa tre chiamate all'advisor e migliora da lì. Abilitalo per lunghi loop di agenti, e tienilo disattivato per compiti brevi.

Mantienilo coerente: Imposta caching una volta e lascialo per l'intera conversazione. Attivarlo e disattivarlo a metà conversazione causa cache miss.



Combinazione con altri strumenti

Lo strumento advisor si compone con altri strumenti lato server e lato client. Aggiungili tutti allo stesso array tools:

tools = [
    {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
    },
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

L'executor può cercare sul web, chiamare l'advisor e usare i tuoi strumenti personalizzati nello stesso turno. Il piano dell'advisor può informare quali strumenti l'executor utilizzerà successivamente.



Best practice



Prompting per compiti di coding e agenti

Lo strumento advisor viene fornito con una descrizione integrata che spinge l'executor a chiamarlo vicino all'inizio di compiti complessi e quando incontra difficoltà. Per compiti di ricerca, tipicamente non è necessario prompting aggiuntivo.

Su compiti di coding e agenti, l'advisor produce intelligenza superiore a costo simile quando riduce le chiamate totali agli strumenti e la lunghezza della conversazione. Due tempistiche guidano questo miglioramento:

1. Una prima chiamata anticipata all'advisor, dopo che alcune letture esplorative sono nella trascrizione.
2. Per compiti difficili, una chiamata finale all'advisor dopo che le scritture di file e gli output dei test sono nella trascrizione.

Se il tuo agente espone altri strumenti simili a planner (ad esempio, uno strumento todo list), istruisci il modello a chiamare l'advisor prima di quegli strumenti in modo che il piano dell'advisor confluisca in essi. Il prompt di sistema suggerito rinforza il pattern di chiamata anticipata. Aggiungi la tua frase di confluenza che punta agli strumenti planner che il tuo agente espone.



Prompt di sistema suggerito per compiti di coding

Senza guida dal prompt di sistema, l'executor tende a chiamare troppo poco l'advisor in alcuni domini, in particolare nei compiti di coding. Per compiti di coding in cui vuoi un timing coerente dell'advisor e circa due o tre chiamate per ogni compito, anteponi i seguenti blocchi al tuo prompt di sistema dell'executor prima di qualsiasi altra frase che menzioni l'advisor.

Guida sul timing:

You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.

Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck — errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.

Come l'executor dovrebbe trattare il consiglio (posiziona direttamente dopo il blocco sul timing):

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.



Prompt di sistema alternativo per Haiku su carichi di lavoro di coding

Claude Haiku 4.5 applica la guida predefinita dell'advisor in modo conservativo. Ciò mantiene il suo tasso di chiamata appropriatamente basso su carichi di lavoro di ricerca e lookup ma rinuncia a qualità su carichi di lavoro di coding, dove una consultazione anticipata dell'advisor si ripaga in modo affidabile. Su un benchmark interno di coding, una variante simile del seguente blocco (l'eccezione read-only nella Hard rule è stata aggiunta dopo la misurazione) ha aumentato i tassi di successo di Haiku di circa 7,5 punti percentuali rispetto al predefinito integrato.

Usa questo blocco al posto dei precedenti blocchi di timing e consiglio quando il tuo executor Haiku esegue prevalentemente carichi di lavoro di coding o di scrittura:

Consult a stronger reviewer who sees your full conversation transcript.

No parameters. When you call advisor(), your entire history -- task, every tool call and result, your reasoning -- is automatically forwarded. The advisor sees exactly what you've done.

Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck -- errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first -- that judgment call is exactly where a second opinion is highest-value.

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

Avvertenza: Su un benchmark interno di comprensione della navigazione (n = 1.266), una variante simile di questo blocco è costata circa 4 punti percentuali di accuratezza rispetto al predefinito integrato. Se il tuo carico di lavoro mescola coding con lookup o retrieval sostanziali, rimani con i blocchi suggeriti, oppure condiziona lo scambio a un segnale di tipo di carico di lavoro che già calcoli.



Aumentare le chiamate all'advisor sugli executor Opus

Gli executor Opus tipicamente chiamano l'advisor a un tasso appropriato senza prompting aggiuntivo. Se il tuo executor Opus sta chiamando troppo poco sul tuo carico di lavoro, aggiungi il seguente checkpoint al tuo prompt di sistema:

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first. That judgment call is exactly where a second opinion is highest-value. (This does not apply to simple factual lookups or arithmetic; those you answer directly.)

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

Avvertenza: Nei test di Anthropic, una variante simile di questo blocco (l'eccezione read-only nella Hard rule è stata aggiunta dopo la misurazione) ha aumentato i tassi di successo sui compiti con chiamate insufficienti di circa 7-10 punti percentuali ma ha causato a Opus di chiamare eccessivamente su compiti la cui prima azione non richiede pianificazione. L'effetto netto è stato approssimativamente neutro su un carico di lavoro misto. Aggiungilo solo se hai osservato Opus saltare l'advisor su compiti in cui una consultazione avrebbe aiutato. Non aggiungerlo come predefinito.



Ridurre la lunghezza dell'output dell'advisor

L'output dell'advisor è il principale fattore di costo dell'advisor, e il max_tokens di primo livello non lo limita. L'advisor vede sia il tuo prompt di sistema sia i tuoi messaggi utente come contesto citato sul compito dell'executor, quindi le istruzioni che si rivolgono direttamente all'advisor vengono seguite in modo molto più affidabile rispetto alle descrizioni in terza persona. Il posizionamento più efficace testato da Anthropic è una riga nel messaggio utente:

(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)

Questa riga può essere prefissata programmaticamente dal tuo framework di agenti prima di inviare la richiesta. Il limite è un vincolo soft. L'advisor occasionalmente lo supera, quindi chiedi circa l'80 percento del tuo tetto reale.

Abbina questo approccio alla guida sul timing in Prompt di sistema suggerito per compiti di coding (o al blocco alternativo per Haiku se l'hai sostituito) per il miglior compromesso costo-qualità. Per un tetto rigido anziché una richiesta soft, consulta Limitare l'output dell'advisor.



Limitare l'output dell'advisor

Imposta max_tokens sulla definizione dello strumento per limitare l'output totale dell'advisor (pensiero più testo) per chiamata:

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-8",
        "max_tokens": 2048,
    }
]

Il valore minimo è 1024. Impostare max_tokens sopra il limite di output del modello advisor restituisce un errore 400. Il limite si applica a ciascuna chiamata all'advisor in modo indipendente e non è condiviso tra le chiamate nella stessa richiesta.

Questo non è solo un troncamento rigido. Il server passa anche all'advisor il suo budget di token rimanente, quindi l'advisor modella la sua risposta per adattarsi.

Punto di partenza consigliato: max_tokens: 2048. Nei test di Anthropic su un benchmark di ragionamento difficile (n = 40 per configurazione), questo ha ridotto l'output medio dell'advisor di circa 7x rispetto a lasciare il limite non impostato, con troncamento quasi nullo e nessun degrado di qualità rilevabile. Il valore minimo di 1024 ha ridotto l'output di circa 10x ma ha troncato circa il 10 percento delle chiamate. Le differenze di accuratezza tra tutte le configurazioni erano entro il rumore a questa dimensione del campione. Valida sul tuo carico di lavoro.

I compiti di ragionamento difficile elicitano output dell'advisor sostanzialmente più lunghi rispetto ai tipici 1.400-1.800 token citati in precedenza per carichi di lavoro più leggeri. Usa questa tabella per dimensionare il rapporto di risparmio, non come baseline universale per l'output dell'advisor.

Quando l'advisor raggiunge il limite, il blocco del risultato contiene stop_reason: "max_tokens". L'API aggiunge anche [Advisor output truncated at max_tokens=2048.] (indicando il tuo limite) al testo del consiglio, in modo che l'executor veda il troncamento nel proprio contesto. Usa stop_reason per rilevare consigli troncati e decidere se aumentare il limite o lasciare che l'executor proceda con guida parziale. Entrambi i segnali appaiono solo quando imposti max_tokens sulla definizione dello strumento.

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "Use a channel-based coordination pattern. The tricky part is\n\n[Advisor output truncated at max_tokens=2048.]",
    "stop_reason": "max_tokens"
  }
}

Controlla output_tokens sulla voce advisor_message corrispondente in usage.iterations per vedere quanto ogni chiamata si è avvicinata al suo limite.

Rispetto all'approccio basato sul prompt, max_tokens è un tetto rigido anziché una richiesta soft. Usa max_tokens quando hai bisogno di un limite garantito per costo o latenza. Usa l'approccio basato sul prompt (o entrambi insieme) quando vuoi orientare verso la brevità senza rischiare un taglio a metà pensiero.



Abbinamento con le impostazioni di effort

Per compiti di coding, abbinare un executor Sonnet a effort medio con un advisor Opus raggiunge un'intelligenza comparabile a Sonnet a effort predefinito, a costo inferiore. Per la massima intelligenza, mantieni l'executor a effort predefinito.



Controllo dei costi

• Per budget a livello di conversazione, conta le chiamate all'advisor lato client. Quando raggiungi il tuo limite, rimuovi lo strumento advisor da tools; non è necessario rimuovere i blocchi advisor_tool_result dalla cronologia dei messaggi (consulta la nota in Conversazioni multi-turno).
• Abilita caching solo per conversazioni in cui ti aspetti tre o più chiamate all'advisor.



Compatibilità dei modelli

Il modello esecutore (il campo model di primo livello) e il modello consulente (il campo model all'interno della definizione dello strumento) devono formare una coppia valida. Il consulente deve essere Claude Sonnet 4.6 o un modello più capace, e deve essere almeno tanto capace quanto l'esecutore. Modelli di pari capacità (ad esempio, Claude Opus 4.7 e Claude Opus 4.8) possono fungere da consulenti l'uno per l'altro.

Se richiedi una coppia non valida, l'API restituisce un errore 400 invalid_request_error che indica la combinazione non supportata.



Disponibilità sulle piattaforme

Lo strumento advisor è disponibile in beta sull'API di Claude e su Claude Platform on AWS. Attualmente non è disponibile su Amazon Bedrock, Google Cloud o Microsoft Foundry.



Advisor su Claude Managed Agents

Le sessioni di Claude Managed Agents supportano anch'esse un advisor, configurato come parte dell'agente anziché come definizione di strumento: aggiungi una voce {"type": "advisor", "model": ...} al roster multiagente dell'agente, e il thread principale della sessione potrà consultare quel modello durante il turno. La voce del roster non accetta le opzioni max_uses, max_tokens o caching, e i consigli vengono forniti come eventi del thread nello stream di eventi della sessione anziché come blocchi advisor_tool_result nella risposta. Consulta Assegnare un advisor alla sessione.



Passaggi successivi