Strumento advisor

Lo strumento advisor consente a un modello esecutore più veloce e meno costoso di consultare un modello advisor 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'esecutore prosegue con l'attività.

Questo schema si adatta ai 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 disporre di 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 esecutore. Per i risultati misurati, incluso il modo in cui il beneficio si riduce man mano che la capacità dell'esecutore si avvicina a quella dell'advisor, consulta Ottimizzare per costo e intelligenza.



Quando usarlo

L'advisor si adatta a queste configurazioni:

• Attualmente usi Sonnet per attività complesse: Aggiungi un advisor di livello superiore. Opus mantiene il costo totale simile o inferiore; Claude Fable 5 massimizza l'incremento di qualità.
• Attualmente usi Haiku e vuoi un salto di intelligenza: Aggiungi un advisor Opus o Fable. Aspettati un costo superiore rispetto a Haiku da solo, ma inferiore rispetto al passaggio dell'esecutore a un modello più grande.

I risultati dipendono dall'attività. Valuta sul tuo carico di lavoro.

L'advisor è meno adatto per Q&A a turno singolo (niente 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 realmente 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 le indicazioni dell'advisor. Con claude-opus-5 come advisor, come in questo avvio rapido, il campo content del blocco è una variante advisor_redacted_result (crittografata; l'esecutore 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 in chiaro advisor_result. Consulta Varianti del risultato per entrambe le forme affiancate e per sapere quali modelli advisor restituiscono quale, e Compatibilità dei modelli per l'elenco completo delle coppie valide.



Come funziona

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

1. L'esecutore emette un blocco server_tool_use con name: "advisor" e un input vuoto. L'esecutore segnala il momento, e il server fornisce il contesto.
2. Anthropic esegue un passaggio di inferenza separato sul modello advisor lato server. L'advisor opera con un proprio "system prompt" (prompt di sistema) fornito da Anthropic e riceve la trascrizione completa dell'esecutore come contesto citato nel suo input. Tale trascrizione include il tuo prompt di sistema, le definizioni degli strumenti, i turni precedenti e i risultati degli strumenti, e il testo che l'esecutore ha prodotto finora in questo turno.
3. La risposta dell'advisor ritorna all'esecutore come blocco advisor_tool_result.
4. L'esecutore 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 successiva (vedi Riprendere un turno in pausa).

L'advisor stesso opera senza strumenti e senza gestione del contesto. I suoi blocchi di pensiero vengono scartati prima che il risultato ritorni. Solo il testo del consiglio raggiunge l'esecutore.



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 (trattato 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 in chiaro advisor_result restituita da un advisor Claude Opus 4.8. L'Avvio rapido usa Claude Opus 5, che restituisce invece la variante crittografata advisor_redacted_result; vedi Varianti del risultato per entrambe le forme affiancate.

{
  "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 a partire dalla trascrizione completa. Nulla di ciò che l'esecutore 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:

Ecco la stessa richiesta inviata due volte, identica tranne che per il model dell'advisor nella definizione dello strumento, che mostra entrambe le varianti.

Con "model": "claude-opus-4-8", il consiglio è in chiaro:

{
  "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..."
  }
}

Con "model": "claude-opus-5", il consiglio è crittografato:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
  }
}

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

Con advisor_result, il campo text contiene un consiglio leggibile. Con advisor_redacted_result, il campo encrypted_content contiene un blob opaco che non puoi leggere. Al turno successivo, il server lo decrittografa e inserisce il testo in chiaro nel prompt dell'esecutore.

In entrambi i casi, ritrasmetti il contenuto alla lettera nei turni successivi. Se cambi modello advisor a metà conversazione, effettua un branch 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'esecutore vede l'errore e continua senza ulteriori consigli. La richiesta stessa non fallisce.

I "rate limit" (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'esecutore fa fallire l'intera richiesta con HTTP 429.



Conversazioni multi-turno

Ripassa all'API il contenuto completo dell'assistente, inclusi i blocchi advisor_tool_result, nei turni successivi. Ritrasmetti i blocchi di risultato alla lettera: con un advisor Claude Opus 5 il content del blocco di risultato è la variante crittografata advisor_redacted_result, e il server la decrittografa e inserisce il consiglio nel prompt dell'esecutore al turno successivo (vedi Varianti del risultato). La meccanica è identica per qualsiasi modello advisor.

client = anthropic.Anthropic()

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

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 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-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 della cronologia 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 alcun advisor_tool_result corrispondente. Per riprendere, aggiungi quel messaggio dell'assistente a messages con il 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'esecutore nella nuova risposta. Un turno ripreso può mettersi nuovamente in pausa. Se accade, 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 essere eseguito; includi lo strumento ogni volta che una chiamata è in sospeso. Se invece l'esecutore 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 della richiesta successiva. Vedi Combinare strumenti server e strumenti client in un turno.



Sollecito a metà conversazione per esecutori che chiamano poco

Se un esecutore Haiku non ha chiamato l'advisor nel suo primo turno da assistente, aggiungi un breve promemoria come messaggio utente aggiuntivo prima del secondo turno dell'assistente. Nella valutazione comportamentale interna di Anthropic questo ha aumentato i tassi di superamento delle attività di circa 7 punti percentuali sugli esecutori Haiku. Sugli esecutori Sonnet, il sollecito in testo semplice non ha avuto effetti misurabili nei test di Anthropic. Le considerazioni sulla tempistica delle chiamate che seguono sono particolarmente rilevanti per Sonnet. Non applicare il sollecito agli esecutori Opus: su Opus ha leggermente ridotto i tassi di superamento.

Con il NUDGE_TURN predefinito di 2, il promemoria arriva tipicamente dopo che il modello si è orientato sull'attività 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 passaggio se il tuo prompt di sistema indica 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 sollecito come messaggio utente a sé stante dopo i risultati degli strumenti, anziché come blocco fratello nello stesso messaggio. I messaggi utente consecutivi sono validi. Nei test di Anthropic su esecutori Haiku e Sonnet si sono comportati in modo equivalente a un blocco fratello. La forma a messaggio separato mantiene inoltre il promemoria chiaramente distinto dall'output degli strumenti.

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

Il sollecito in testo semplice è molto saliente sugli esecutori Haiku e Sonnet: dal 74 percento (Sonnet) al 98 percento (Haiku) dei tentativi sollecitati nei test di Anthropic ha chiamato l'advisor immediatamente al turno 2. Se questo arriva prima che il tuo esecutore 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 di base del tuo esecutore prima di aggiungere il sollecito. Se l'esecutore chiama già l'advisor in modo affidabile e la sua prima chiamata arriva tipicamente al turno N, imposta NUDGE_TURN maggiore di N. Nei test di Anthropic, un sollecito al turno 2 su carichi di lavoro in cui la prima chiamata di base era al turno 7 o successivo è risultato correlato a un calo delle prestazioni sull'attività 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 sollecito ha aumentato il coinvolgimento senza costi in termini di prestazioni sull'attività.

Per forzare una consultazione su una richiesta specifica invece di sollecitare, 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 "extended thinking" (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 sotto-inferenza dell'advisor non viene trasmessa in streaming. Lo stream dell'esecutore 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 sta iniziando una chiamata all'advisor. La pausa inizia quando quel blocco si chiude (content_block_stop). Durante la pausa, lo stream è silenzioso tranne che per i 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'esecutore 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": 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'esecutore. I token dell'advisor non vengono sommati 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 esecutore.

Ogni campo usage di primo livello è la somma di quel campo su tutte le iterazioni dell'esecutore, inclusi input_tokens, output_tokens e cache_read_input_tokens. Poiché ogni iterazione dell'esecutore reinvia la conversazione in crescita, 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 ripartizione completa per iterazione quando costruisci la logica di tracciamento dei costi.

L'output dell'advisor è tipicamente di 400-700 token di testo, o 1.400-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'esecutore alla sua tariffa inferiore.

Il max_tokens di primo livello si applica solo all'output dell'esecutore. Non limita i token della sotto-inferenza dell'advisor. Per limitare direttamente l'output dell'advisor, imposta max_tokens nella definizione dello strumento. I token dell'advisor inoltre non attingono da alcun budget di attività applicato all'esecutore.

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



Cache dei prompt dell'advisor

Esistono due livelli di caching indipendenti.



Caching lato esecutore

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 produce un hit. Il prompt dell'esecutore contiene sempre il consiglio in chiaro indipendentemente dal fatto che il tuo client abbia ricevuto text o encrypted_content, quindi il comportamento della cache è identico per entrambe le varianti del risultato.



Caching lato advisor

Imposta caching nella definizione dello strumento per abilitare la "prompt caching" (cache dei prompt) per la trascrizione propria 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 all'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 il delta. Vedrai cache_read_input_tokens diventare diverso da zero dalla seconda iterazione advisor_message in poi.

Quando abilitarlo: La scrittura in cache costa più di quanto le letture facciano risparmiare quando l'advisor viene chiamato due volte o meno 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 attività brevi.

Mantienilo coerente: Imposta caching una volta e lascialo invariato 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'esecutore può cercare sul web, chiamare l'advisor e usare i tuoi strumenti personalizzati nello stesso turno. Il piano dell'advisor può orientare quali strumenti l'esecutore utilizzerà successivamente.



Best practice



Prompting per attività di coding e di agenti

Lo strumento advisor viene fornito con una descrizione integrata che spinge l'esecutore a chiamarlo verso l'inizio delle attività complesse e quando incontra difficoltà. Per le attività di ricerca, in genere non è necessario alcun prompting aggiuntivo.

Nelle attività di coding e di agenti, 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 le attività 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 di tipo pianificatore (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 rafforza lo schema della chiamata anticipata. Aggiungi una tua frase di convogliamento che punti agli strumenti pianificatori esposti dal tuo agente.



Prompt di sistema suggerito per attività di coding

Senza un orientamento nel prompt di sistema, l'esecutore tende a chiamare poco l'advisor in alcuni domini, in particolare nelle attività di coding. Per le attività di coding in cui desideri una tempistica coerente dell'advisor e circa due o tre chiamate per ogni attività, anteponi i seguenti blocchi al prompt di sistema del tuo esecutore prima di qualsiasi altra frase che menzioni l'advisor.

Indicazioni 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'esecutore dovrebbe trattare il consiglio (posizionalo 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 coding

Claude Haiku 4.5 applica le indicazioni predefinite dell'advisor in modo conservativo. Questo mantiene il suo tasso di chiamata adeguatamente basso sui carichi di lavoro di ricerca e lookup, ma rinuncia a qualità sui carichi di lavoro di coding, dove una consultazione anticipata dell'advisor si ripaga in modo affidabile. Su un benchmark di coding interno, una variante simile del blocco seguente (l'eccezione per la sola lettura nella Hard rule è stata aggiunta dopo la misurazione) ha aumentato i tassi di superamento di Haiku di circa 7,5 punti percentuali rispetto al predefinito integrato.

Usa questo blocco al posto dei precedenti blocchi su tempistica e consiglio quando il tuo esecutore 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 una quantità sostanziale di lookup o retrieval, resta con i blocchi suggeriti, oppure condiziona la sostituzione a un segnale di tipo di carico di lavoro che già calcoli.



Aumentare le chiamate all'advisor sugli esecutori Opus

Gli esecutori Opus in genere chiamano l'advisor a un tasso appropriato senza prompting aggiuntivo. Se il tuo esecutore Opus chiama 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 Hard rule è stata aggiunta dopo la misurazione) ha aumentato i tassi di superamento sulle attività con poche chiamate di circa 7-10 punti percentuali, ma ha portato Opus a chiamare troppo su attività la cui prima azione non richiede pianificazione. L'effetto netto è stato sostanzialmente neutro su un carico di lavoro misto. Aggiungilo solo se hai osservato Opus saltare l'advisor su attività 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 sull'attività dell'esecutore, quindi le istruzioni rivolte 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 morbido. L'advisor occasionalmente lo supera, quindi chiedi circa l'80 percento del tuo tetto reale.

Abbina questo approccio alle indicazioni sulla tempistica in Prompt di sistema suggerito per attività di coding (o al blocco alternativo per Haiku se lo hai sostituito) per il miglior compromesso tra costo e qualità. Per un tetto rigido anziché una richiesta morbida, vedi Limitare l'output dell'advisor.



Limitare l'output dell'advisor

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

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

Il valore minimo è 1024. Impostare max_tokens al di sopra del limite di output proprio 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.

Non si tratta solo di 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 7 volte rispetto a lasciare il limite non impostato, con troncamento quasi nullo e nessun peggioramento 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 con questa dimensione del campione. Convalida sul tuo carico di lavoro.

Le attività 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 riferimento universale per l'output dell'advisor.

Quando l'advisor raggiunge il limite, il blocco di risultato contiene stop_reason: "max_tokens" su entrambe le varianti del risultato, qualunque modello advisor tu usi. Usa stop_reason per rilevare i consigli troncati e decidere se aumentare il limite o lasciare che l'esecutore proceda con indicazioni parziali. L'API aggiunge inoltre [Advisor output truncated at max_tokens=2048.] (indicando il tuo limite) al testo del consiglio, in modo che l'esecutore veda il troncamento nel proprio contesto; con un advisor advisor_result in chiaro quel marcatore è visibile anche al tuo client. Entrambi i segnali appaiono solo quando imposti max_tokens nella definizione dello strumento.

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
    "stop_reason": "max_tokens"
  }
}

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

Rispetto all'approccio basato sul prompt, max_tokens è un tetto rigido anziché una richiesta morbida. 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à ragionamento.



Abbinamento con le impostazioni di effort

Per le attività di coding, abbinare un esecutore Sonnet a effort medio con un advisor Opus raggiunge un'intelligenza paragonabile a Sonnet a effort predefinito, a un costo inferiore. Per la massima intelligenza, mantieni l'esecutore 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; non è necessario eliminare i blocchi advisor_tool_result dalla cronologia dei messaggi (vedi la nota in Conversazioni multi-turno).
• Abilita caching solo per le conversazioni in cui prevedi 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 altrettanto capace dell'esecutore. Modelli di pari capacità (ad esempio, Claude Opus 4.7 e Claude Opus 4.8) possono consigliarsi a vicenda.

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 consulente è disponibile in beta sulla Claude API e su Claude Platform su AWS. Non è attualmente disponibile su Amazon Bedrock, Google Cloud o Microsoft Foundry.



Consulente su Claude Managed Agents

Anche le sessioni di Claude Managed Agents supportano un consulente, 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 a metà turno. La voce del roster non accetta le opzioni max_uses, max_tokens o caching, e i consigli vengono forniti come eventi di thread sul flusso di eventi della sessione anziché come blocchi advisor_tool_result nella risposta. Consulta Assegnare un consulente alla sessione.



Passaggi successivi