Strumento advisor

Lo strumento advisor consente a un "executor model" (modello esecutore) più veloce e meno costoso di consultare un "advisor model" (modello consulente) di maggiore intelligenza 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 schema si adatta a carichi di lavoro agentici a lungo orizzonte (agenti di programmazione, uso del computer, pipeline di ricerca in più fasi) in cui la maggior parte dei turni è meccanica ma avere un piano eccellente è fondamentale. Ottieni una qualità vicina a quella dell'advisor usato da solo, mentre la maggior parte della generazione di token avviene alle tariffe del modello executor. Per i risultati misurati, incluso il modo in cui il beneficio si riduce man mano che le capacità dell'executor si avvicinano a quelle dell'advisor, consulta Ottimizzare costi e intelligenza.

Quando usarlo

L'advisor è adatto 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.1 massimizza il miglioramento della 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'executor a un modello più grande.

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

L'advisor è meno adatto per domande e risposte 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 davvero tutte le 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'executor la legge lato server, ma il tuo client no). Per vedere direttamente il testo del consiglio nella risposta, usa invece claude-opus-4-8 come modello advisor, che restituisce la variante in chiaro advisor_result. Consulta Varianti del risultato per confrontare le due forme e sapere quali modelli advisor restituiscono ciascuna, 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 decide 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 lato server un passaggio di inferenza separato sul modello advisor. L'advisor viene eseguito con un proprio "system prompt" (prompt di sistema) fornito da Anthropic e riceve nel suo input l'intera trascrizione dell'executor come contesto citato. 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'executor ha prodotto finora in questo turno.
3. La risposta dell'advisor torna all'executor come blocco advisor_tool_result.
4. L'executor continua a generare, tenendo conto del consiglio.

Tutto questo avviene all'interno di una singola richiesta /v1/messages, senza ulteriori round trip da parte tua. L'eccezione è un turno che si mette in pausa durante la 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 ragionamento vengono scartati prima che il risultato venga restituito. 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, non è un marcatore di breakpoint. È un interruttore on/off. È il server a determinare dove collocare 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 (trattata negli output strutturati). Consulta il Riferimento degli strumenti per la loro semantica.

Struttura della risposta

Chiamata all'advisor riuscita

Quando l'advisor viene chiamato, nel contenuto dell'assistente un blocco server_tool_use è seguito da un blocco advisor_tool_result. 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; consulta Varianti del risultato per confrontare le due forme.

{
  "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 a partire dall'intera trascrizione. 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:

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 includono un campo stop_reason quando imposti max_tokens nella definizione dello strumento, e lo omettono quando non lo fai. Contiene il motivo di arresto 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'executor.

In entrambi i casi, rinvia il contenuto alla lettera nei turni successivi. Se cambi modello advisor a metà conversazione, distingui in base a 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 prosegue senza ulteriori consigli. La richiesta in sé non fallisce.

I "rate limit" (limiti di velocità) dell'advisor attingono allo 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

Rinvia all'API l'intero contenuto dell'assistente, inclusi i blocchi advisor_tool_result, nei turni successivi. Rinvia i blocchi di risultato così come sono: 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'executor al turno successivo (consulta Varianti del risultato). Il meccanismo è identico 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 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 anche se 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 un corrispondente advisor_tool_result. Per riprendere, aggiungi quel messaggio dell'assistente a messages con il contenuto invariato, mantenendo il blocco server_tool_use, e invia di nuovo la richiesta con lo stesso strumento advisor e lo stesso header beta. Non è necessario aggiungere un messaggio utente né 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 di nuovo in pausa. In tal caso, ripeti lo stesso passaggio. Omettere lo strumento advisor dalla richiesta di ripresa restituisce un errore 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'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 della richiesta successiva. Consulta Combinare strumenti server e strumenti client in un unico turno.

Sollecito a metà conversazione per executor che chiamano poco l'advisor

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

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-5"},
    # ... i tuoi altri 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-5-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 == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it
    if response.stop_reason != "tool_use":
        break  # end_turn, or a stop such as max_tokens that needs handling (see below)

    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})

Il ciclo termina con qualsiasi motivo di arresto diverso da tool_use o pause_turn. Se max_tokens tronca una risposta, rimuovi il turno dell'assistente troncato da messages e riprova con un max_tokens più alto. Quando quel turno non contiene alcun blocco tool_use, puoi invece mantenerlo e continuare la risposta con un nuovo messaggio utente. Reinviare il turno dell'assistente troncato come ultimo messaggio costituisce un prefill, che Claude 4.6 e i modelli successivi rifiutano.

Aggiungi il sollecito come messaggio utente a sé stante dopo i risultati degli strumenti, anziché come blocco affiancato nello stesso messaggio. I messaggi utente consecutivi sono validi. Nei test di Anthropic su executor Claude Haiku 4.5 e Sonnet si sono comportati in modo equivalente a un blocco affiancato. 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 compiti banalmente semplici verso una consultazione non necessaria. Se il tuo carico di lavoro mescola compiti semplici e complessi, valuta di aumentare NUDGE_TURN a 3 in modo che i compiti a due turni si completino prima che il sollecito scatti, oppure subordina il sollecito 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 ai casi di reale incertezza"), salta del tutto il sollecito, perché le due istruzioni sono in conflitto.

Il sollecito in testo semplice è molto saliente sugli executor Claude Haiku 4.5 e Sonnet: dal 74 percento (Sonnet) al 98 percento (Claude Haiku 4.5) dei tentativi sollecitati 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 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 sollecito. Se l'executor chiama già l'advisor in modo affidabile e la sua prima chiamata avviene tipicamente al turno N, imposta NUDGE_TURN a un valore maggiore di N. Nei test di Anthropic, un sollecito al turno 2 su carichi di lavoro in cui la prima chiamata di base avveniva al turno 7 o successivo è stato correlato a un calo delle prestazioni sui compiti da 3 a 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 alcun costo in termini di prestazioni sui compiti.

Per forzare una consultazione su una richiesta specifica invece di sollecitare, imposta tool_choice su {"type": "tool", "name": "advisor"}, nel rispetto dei vincoli descritti in Forzare l'uso degli strumenti. L'uso forzato degli strumenti non può essere combinato con il ragionamento esteso manuale (thinking: {type: "enabled"}): l'API restituisce un errore 400 invalid_request_error se li abiliti entrambi. Il ragionamento adattivo supporta l'uso forzato degli strumenti. Gli executor Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1 rifiutano i tipi tool e any di tool_choice, quindi su quei modelli usa invece il sollecito nel prompt.

Streaming

La sotto-inferenza dell'advisor non viene trasmessa in 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, fatta eccezione per i keepalive SSE standard ping emessi all'incirca ogni 30 secondi. Le chiamate brevi all'advisor potrebbero non mostrare alcun ping.

Quando l'advisor termina, l'advisor_tool_result arriva completo in un singolo evento content_block_start (senza 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": 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 sommati ai 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 reinvia la conversazione in crescita, gli input delle iterazioni successive includono l'output di quelle 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 monitoraggio dei costi.

L'output dell'advisor è tipicamente di 400-700 token di testo, ovvero 1.400-1.800 token in totale incluso il ragionamento. Il risparmio sui costi deriva dal fatto che l'advisor non genera il tuo output finale completo. Lo fa l'executor, alla sua tariffa più bassa.

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 nella definizione dello strumento. I token dell'advisor inoltre non attingono ad 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 in Priority Tier solo se la tua organizzazione detiene anche un impegno sul modello advisor.

Cache dei prompt dell'advisor

Esistono due livelli di cache indipendenti.

Cache lato executor

Il blocco advisor_tool_result può essere memorizzato nella 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'executor 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.

Cache lato advisor

Imposta caching nella 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 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 nella cache, e la chiamata successiva legge fino a quel punto e paga solo per la differenza. Vedrai cache_read_input_tokens diventare diverso da zero dalla seconda iterazione advisor_message in poi.

Quando abilitarla: La scrittura nella cache costa più di quanto facciano risparmiare le letture quando l'advisor viene chiamato due volte o meno per conversazione. La cache va in pareggio a circa tre chiamate all'advisor e migliora da lì in poi. Abilitala per i loop di agenti lunghi e lasciala disattivata per i compiti brevi.

Mantienila coerente: Imposta caching una volta e lasciala così per l'intera conversazione. Disattivarla e riattivarla a metà conversazione causa cache miss.

Combinazione con altri strumenti

Lo strumento advisor si combina 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ò orientare la scelta degli strumenti che l'executor utilizzerà successivamente.

Best practice

Prompt per compiti di programmazione e agentici

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

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

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

Se il tuo agente espone altri strumenti simili a un pianificatore (ad esempio, uno strumento per liste di cose da fare), chiedi al modello di 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 che indirizzi il piano verso gli strumenti di pianificazione esposti dal tuo agente.

Prompt di sistema suggerito per i compiti di programmazione

Senza indicazioni nel prompt di sistema, l'executor tende a chiamare poco l'advisor in alcuni domini, in particolare nei compiti di programmazione. Per i compiti di programmazione in cui desideri una tempistica coerente delle chiamate all'advisor e circa due o tre chiamate per compito, anteponi i seguenti blocchi al prompt di sistema dell'executor, 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'executor dovrebbe trattare il consiglio (da posizionare subito 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 programmazione

Claude Haiku 4.5 applica le indicazioni predefinite sull'advisor in modo conservativo. Ciò mantiene il suo tasso di chiamate opportunamente basso sui carichi di lavoro di ricerca e consultazione, ma sacrifica qualità sui carichi di lavoro di programmazione, dove una consultazione anticipata dell'advisor si ripaga in modo affidabile. Su un benchmark interno di programmazione, una variante molto simile del blocco seguente (l'eccezione per le operazioni di sola lettura nella regola rigida è stata aggiunta dopo la misurazione) ha aumentato i tassi di superamento di Haiku di circa 7,5 punti percentuali rispetto al valore predefinito integrato.

Usa questo blocco al posto dei blocchi precedenti su tempistica e consiglio quando il tuo executor Haiku esegue prevalentemente carichi di lavoro di programmazione 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 durante la navigazione (n = 1.266), una variante molto simile di questo blocco ha comportato una perdita di accuratezza di circa 4 punti percentuali rispetto al valore predefinito integrato. Se il tuo carico di lavoro combina la programmazione con una quantità significativa di consultazione o recupero di informazioni, mantieni i blocchi suggeriti, oppure subordina la sostituzione a un segnale sul tipo di carico di lavoro che già calcoli.

Aumentare le chiamate all'advisor sugli executor Opus

Gli executor Opus in genere chiamano l'advisor con una frequenza appropriata senza prompt aggiuntivi. Se il tuo executor Opus chiama poco l'advisor 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 molto simile di questo blocco (l'eccezione per le operazioni di sola lettura nella regola rigida è stata aggiunta dopo la misurazione) ha aumentato i tassi di superamento sui compiti con poche chiamate di circa 7-10 punti percentuali, ma ha portato Opus a chiamare troppo l'advisor su compiti la cui prima azione non richiede pianificazione. L'effetto netto è stato sostanzialmente nullo 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 impostazione predefinita.

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 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 in modo programmatico dal tuo framework per agenti prima di inviare la richiesta. Il limite è un vincolo flessibile. 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 i compiti di programmazione (o al blocco alternativo per Haiku, se lo hai adottato) per ottenere il miglior compromesso tra costo e qualità. Per un tetto rigido anziché una richiesta flessibile, consulta Limitare l'output dell'advisor.

Limitare l'output dell'advisor

Imposta max_tokens nella definizione dello strumento per limitare l'output totale dell'advisor (ragionamento 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 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 comunica anche all'advisor il budget di token rimanente, così l'advisor adatta la propria risposta per rientrarvi.

Punto di partenza consigliato: max_tokens: 2048. Nei test di Anthropic su un benchmark di ragionamento difficile (n = 40 per configurazione), questo valore ha ridotto l'output medio dell'advisor di circa 7 volte rispetto a lasciare il limite non impostato, con un 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 rientravano nel rumore statistico con questa dimensione del campione. Verifica 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 indicati in precedenza per carichi di lavoro più leggeri. Usa questa tabella per stimare 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" in entrambe le varianti del risultato, qualunque sia il modello advisor che usi. Usa stop_reason per rilevare i consigli troncati e decidere se aumentare il limite o lasciare che l'executor proceda con indicazioni parziali. L'API aggiunge inoltre [Advisor output truncated at max_tokens=2048.] (con il tuo limite) al testo del consiglio, così l'executor vede il troncamento nel proprio contesto; con un advisor che restituisce advisor_result in chiaro, quel marcatore è visibile anche al tuo client. Entrambi i segnali compaiono 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 proprio limite.

Rispetto all'approccio basato sul prompt, max_tokens è un tetto rigido anziché una richiesta flessibile. Usa max_tokens quando hai bisogno di un limite garantito per costi o latenza. Usa l'approccio basato sul prompt (o entrambi insieme) quando vuoi favorire la brevità senza rischiare un'interruzione a metà ragionamento.

Abbinamento con le impostazioni di effort

Per le attività di programmazione, abbinare un executor (esecutore) Sonnet con effort (livello di impegno) medio a un advisor (consulente) Opus offre un'intelligenza paragonabile a quella di Sonnet con effort predefinito, a un costo inferiore. Per la massima intelligenza, mantieni l'executor all'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 (consulta 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 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 capace almeno quanto l'executor. Modelli di pari capacità (ad esempio, Claude Opus 4.7 e Claude Opus 4.8) possono fare da advisor l'uno all'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 on AWS. Attualmente non è disponibile su Amazon Bedrock, Google Cloud o Microsoft Foundry.

Advisor su Claude Managed Agents

Anche le sessioni di Claude Managed Agents supportano un advisor, configurato come parte dell'agente anziché come definizione di strumento: imposta "advisor": {"type": "enabled", "model": ...} nel blocco multiagent dell'agente, e il thread principale della sessione potrà consultare quel modello a metà turno. L'impostazione non accetta le opzioni max_uses, max_tokens o caching, e i consigli vengono forniti come eventi del thread sullo stream di eventi della sessione anziché come blocchi advisor_tool_result nella risposta. Consulta Fornisci un advisor alla sessione.

Passaggi successivi