Strumento advisor

Lo strumento advisor consente a un executor model (modello esecutore) più veloce e a costo inferiore di consultare un advisor model (modello consulente) di intelligenza superiore durante la generazione per ottenere indicazioni strategiche. L'advisor legge l'intera conversazione, produce un piano o una correzione di rotta, e l'executor prosegue con il compito.

Questo pattern si adatta a carichi di lavoro agentici a lungo orizzonte (agenti di codifica, uso del computer, pipeline di ricerca multi-step) 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 Opus come advisor per un miglioramento della qualità a un costo totale simile o inferiore.
• Attualmente usi Haiku e vuoi un salto di intelligenza: Aggiungi Opus come advisor. Aspettati un costo superiore rispetto al solo Haiku, ma inferiore rispetto al passaggio dell'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 (non c'è nulla da pianificare), per selettori di modello puramente pass-through in cui i tuoi utenti scelgono già il proprio compromesso tra costo e qualità, o per carichi di lavoro in cui ogni turno richiede genuinamente la piena capacità del modello advisor.



Compatibilità dei modelli

Il modello executor (il campo model di primo livello) e il modello advisor (il campo model all'interno della definizione dello strumento) devono formare una coppia valida. L'advisor deve essere Claude Sonnet 4.6 o un modello più capace, e deve essere almeno altrettanto capace dell'executor. Modelli di pari capacità (ad esempio, Claude Opus 4.7 e Claude Opus 4.8) possono fungere da advisor 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 sulla Claude API e su Claude Platform su AWS. Non è attualmente disponibile su Amazon Bedrock, Google Cloud o Microsoft Foundry.



Avvio rapido

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

print(response)



Come funziona

Quando aggiungi lo strumento advisor al tuo array tools, il modello executor determina quando chiamarlo, come qualsiasi altro strumento. Quando l'executor invoca 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 da parte tua. L'eccezione è un turno che si mette in pausa a metà chiamata, che riprendi con una richiesta di follow-up (vedi 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). Vedi il Riferimento degli strumenti per la loro semantica.



Struttura della risposta



Chiamata all'advisor riuscita

Quando l'advisor viene invocato, un blocco server_tool_use è seguito da un blocco advisor_tool_result nel contenuto dell'assistente:

{
  "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 campo 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 è un'unione discriminata. Per le chiamate riuscite, la variante dipende dal modello advisor:

Gli advisor 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 sotto-chiamata dell'advisor, tipicamente "end_turn", o "max_tokens" quando il limite viene raggiunto. I valori corrispondono allo stop_reason di primo livello della Messages API.

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

In entrambi i casi, restituisci il contenuto letteralmente nei turni successivi. Se cambi modello advisor a metà conversazione, usa una diramazione su content.type per gestire entrambe le forme.



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 il contenuto completo dell'assistente, inclusi i blocchi advisor_tool_result, all'API nei turni successivi:

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-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Aggiungi il contenuto completo 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-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

Se ometti lo strumento advisor da tools in un turno di follow-up mentre la cronologia dei messaggi contiene ancora blocchi advisor_tool_result, l'API restituisce un errore 400 invalid_request_error.



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 alcun 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 lo stesso 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. Se ciò accade, ripeti lo stesso passaggio. Omettere lo strumento advisor dalla richiesta di ripresa restituisce un errore 400 invalid_request_error. 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 al solito, e la chiamata all'advisor in sospeso viene eseguita all'inizio di quella richiesta successiva. Vedi Combinare strumenti server e strumenti client in un turno.



Promemoria a metà conversazione per executor che chiamano troppo poco

Se un executor Haiku non ha chiamato l'advisor nel suo primo turno da assistente, aggiungi un breve promemoria come messaggio utente aggiuntivo prima del secondo turno da 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 alcun effetto misurabile nei test di Anthropic. Le considerazioni sul momento della chiamata 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 valore predefinito di NUDGE_TURN pari a 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-4-8"},
    # ... 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(
        b.type == "server_tool_use" and b.name == "advisor" for b 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 passaggio se il tuo prompt di sistema indica già al modello di effettuare chiamate con parsimonia.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

Aggiungi il promemoria come messaggio utente a sé stante dopo i risultati degli strumenti piuttosto che come blocco fratello nello stesso messaggio. Messaggi utente consecutivi sono validi. Nei test di Anthropic su 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à un linguaggio di moderazione ("riserva l'advisor per l'incertezza genuina"), salta del tutto 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 hanno chiamato l'advisor immediatamente al turno 2. Se ciò avviene prima che il tuo executor abbia letto il problema o raccolto il contesto, la chiamata all'advisor risultante ha poco contesto e può sostituire una chiamata successiva meglio temporizzata. Misura il turno di prima chiamata di base 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 di base era al turno 7 o successivo era correlato a un calo delle prestazioni del compito di 3-4 punti percentuali. Su un carico di lavoro di navigazione in cui il tasso di chiamata di base era dell'86 percento, lo stesso promemoria ha aumentato il coinvolgimento senza alcun costo in termini di 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: l'API restituisce un errore 400 invalid_request_error se abiliti entrambi.



Streaming

La sotto-inferenza dell'advisor non usa lo 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 ad eccezione dei keepalive SSE ping standard emessi circa ogni 30 secondi. Le chiamate brevi all'advisor potrebbero non mostrare alcun 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 sotto-inferenza separata fatturata alle tariffe del modello advisor. L'utilizzo è riportato nell'array usage.iterations[]:

{
  "usage": {
    "input_tokens": 412,
    "cache_read_input_tokens": 0,
    "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-4-8",
        "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 sono 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.

Le regole di aggregazione differiscono per campo. Il campo output_tokens di primo livello è la somma di tutte le iterazioni dell'executor. I campi input_tokens e cache_read_input_tokens di primo livello riflettono solo la prima iterazione dell'executor. Gli input delle iterazioni successive dell'executor non vengono risommati perché includono i token di output precedenti. Usa usage.iterations per una suddivisione completa per iterazione quando costruisci la 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. Lo fa l'executor alla sua tariffa inferiore.

Il max_tokens di primo livello si applica solo all'output dell'executor. Non limita i token della sotto-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 a 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 nella cache come qualsiasi altro blocco di contenuto. Un breakpoint cache_control posizionato dopo di esso in un turno successivo viene trovato nella cache. Il prompt dell'executor contiene sempre il consiglio in testo 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.



Caching lato advisor

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

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-8",
        "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 nella 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 nella seconda iterazione advisor_message e in quelle successive.

Quando abilitarlo: La scrittura nella cache costa più di quanto le letture facciano risparmiare 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ì in poi. Abilitalo per loop di agenti lunghi, 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-4-8",
    },
    {
        "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 codifica e agentici

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

Nei compiti di codifica e agentici, l'advisor produce un'intelligenza superiore a costo simile quando riduce il numero totale di chiamate agli strumenti e la lunghezza della conversazione. Due tempistiche guidano questo miglioramento:

1. Una prima chiamata all'advisor anticipata, 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 pianificatori (ad esempio, uno strumento di lista di cose da fare), 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 rafforza il pattern della chiamata anticipata. Aggiungi la tua frase di convogliamento che punti a qualunque strumento di pianificazione il tuo agente esponga.



Prompt di sistema suggerito per compiti di codifica

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

Guida sulla tempistica:

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 sulla tempistica):

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 codifica

Claude Haiku 4.5 applica la guida predefinita dell'advisor in modo conservativo. Questo mantiene il suo tasso di chiamata appropriatamente basso su carichi di lavoro di ricerca e consultazione ma rinuncia a qualità sui carichi di lavoro di codifica, dove una consultazione anticipata dell'advisor si ripaga in modo affidabile. Su un benchmark interno di codifica, una variante simile del seguente blocco (l'eccezione per la sola lettura nella regola Hard è 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 sulla tempistica e sui consigli quando il tuo executor Haiku esegue prevalentemente carichi di lavoro di codifica 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 codifica con una sostanziale attività di consultazione o recupero, 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 chiama 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 per la sola lettura nella regola Hard è 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 un eccesso di chiamate da parte di Opus 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 sarebbe stata utile. 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 anteposta programmaticamente dal tuo framework di agenti prima di inviare la richiesta. Il limite è un vincolo soft. L'advisor occasionalmente lo supera, quindi richiedi circa l'80 percento del tuo vero tetto massimo.

Abbina questo approccio alla guida sulla tempistica in Prompt di sistema suggerito per compiti di codifica (o al blocco alternativo per Haiku se lo hai sostituito) per il miglior compromesso tra costo e qualità. Per un tetto rigido piuttosto che una richiesta soft, vedi 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 al di sopra del limite di output del modello advisor stesso 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, in modo che l'advisor modelli 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 7 volte rispetto a lasciare il limite non impostato, con troncamento quasi nullo e nessun degrado rilevabile della qualità. Il valore minimo di 1024 ha ridotto l'output di circa 10 volte 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 difficili producono un output dell'advisor sostanzialmente più lungo 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 base 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 una 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 piuttosto che 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 i compiti di codifica, abbinare un executor Sonnet a effort medio con un advisor Opus raggiunge un'intelligenza paragonabile a Sonnet a effort predefinito, a costo inferiore. Per la massima intelligenza, mantieni l'executor a effort predefinito.



Controllo dei costi

• Per i budget a livello di conversazione, conta le chiamate all'advisor lato client. Quando raggiungi il tuo limite, rimuovi lo strumento advisor da tools e elimina tutti i blocchi advisor_tool_result dalla cronologia dei messaggi per evitare un errore 400 invalid_request_error (vedi la nota in Conversazioni multi-turno).
• Abilita caching solo per le conversazioni in cui prevedi tre o più chiamate all'advisor.



Prossimi passi