Strumento advisor

Lo strumento advisor consente a un modello executor più veloce e a basso costo di consultare un modello advisor di intelligenza superiore durante la generazione per ricevere una guida strategica. L'advisor legge l'intera conversazione, produce un piano o una correzione di rotta (tipicamente da 400 a 700 token di testo, da 1.400 a 1.800 token totali incluso il thinking), e l'executor continua con l'attività.

Questo modello si adatta a carichi di lavoro agentici a lungo termine (agenti di codifica, utilizzo del computer, pipeline di ricerca multi-step) dove la maggior parte dei turni è meccanica ma avere un piano eccellente è cruciale. Ottieni una qualità quasi pari a quella dell'advisor da solo mentre la maggior parte della generazione di token avviene alle velocità del modello executor.

Quando usarlo

I benchmark iniziali mostrano guadagni significativi per queste configurazioni:

• Attualmente usi Sonnet su attività complesse: Aggiungi Opus come advisor per un miglioramento della qualità a costo simile o inferiore.
• Attualmente usi Haiku e desideri un passo avanti nell'intelligenza: Aggiungi Opus come advisor. Aspettati un costo superiore a Haiku da solo, ma inferiore al passaggio dell'executor a un modello più grande.

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

L'advisor è un adattamento più debole per Q&A a turno singolo (niente da pianificare), selettori di modelli pass-through puri dove i tuoi utenti scelgono già il loro compromesso tra costo e qualità, o carichi di lavoro dove ogni turno richiede genuinamente la piena capacità del modello advisor.

Compatibilità dei modelli

Il modello executor (il campo model di livello superiore) e il modello advisor (il campo model all'interno della definizione dello strumento) devono formare una coppia valida. L'advisor deve essere almeno altrettanto capace dell'executor.

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

Disponibilità della piattaforma

Lo strumento advisor è disponibile in beta su Claude API (Anthropic).

Avvio rapido

Come funziona

Quando aggiungi lo strumento advisor al tuo array tools, il modello executor decide quando chiamarlo, proprio 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 i tempi; il server fornisce il contesto.
2. Anthropic esegue un pass di inferenza separato sul modello advisor lato server, passando la trascrizione completa dell'executor. L'advisor vede il prompt di sistema, tutte le definizioni degli strumenti, tutti i turni precedenti e tutti i risultati degli strumenti precedenti.
3. La risposta dell'advisor ritorna all'executor come blocco advisor_tool_result.
4. L'executor continua a generare, informato dal consiglio.

Tutto questo accade all'interno di una singola richiesta /v1/messages. Nessun viaggio di andata e ritorno aggiuntivo da parte tua.

L'advisor stesso funziona senza strumenti e senza gestione del contesto. I suoi blocchi di thinking 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 decide dove vanno i confini della cache.

Struttura della risposta

Chiamata 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..."
    }
  ]
}

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

Varianti di risultato

Il campo advisor_tool_result.content è un'unione discriminata. Quale variante ricevi dipende dal modello advisor:

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 decripta e renderizza il testo semplice nel prompt dell'executor.

In entrambi i casi, fai circolare il contenuto verbatim nei turni successivi. Se cambi modelli advisor a metà conversazione, ramifica su content.type per gestire entrambe le forme.

Risultati di errore

Se la chiamata 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 provengono 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 fallisce 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:

import anthropic

client = anthropic.Anthropic()

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

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

# Append the full response content, including any advisor_tool_result blocks
messages.append({"role": "assistant", "content": response.content})

# Continue the conversation
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 400 invalid_request_error.

Streaming

La sub-inferenza dell'advisor non esegue lo streaming. Lo stream dell'executor si mette in pausa mentre l'advisor funziona, quindi il risultato completo arriva in un singolo evento.

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

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

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

Utilizzo e fatturazione

Le chiamate advisor vengono eseguite come una sub-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-7",
        "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 livello superiore riflettono solo i token dell'executor. I token dell'advisor non vengono incorporati nei totali di livello superiore perché vengono fatturati a una velocità diversa. Le iterazioni con type: "advisor_message" vengono fatturate alle tariffe del modello advisor; le iterazioni con type: "message" vengono fatturate alle tariffe del modello executor.

Le regole di aggregazione differiscono per campo. L'output_tokens di livello superiore è la somma di tutte le iterazioni dell'executor. L'input_tokens di livello superiore e cache_read_input_tokens riflettono solo la prima iterazione dell'executor; gli input delle iterazioni dell'executor successive 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 thinking. I risparmi sui costi derivano dal fatto che l'advisor non genera il tuo output finale completo; l'executor lo fa alla sua velocità inferiore.

Il max_tokens di livello superiore si applica solo all'output dell'executor. Non limita i token della sub-inferenza dell'advisor. I token dell'advisor inoltre non vengono prelevati da alcun budget di attività applicato all'executor.

Caching del prompt 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 avrà successo. Il prompt dell'executor contiene sempre il consiglio in testo semplice indipendentemente dal fatto che il tuo client abbia ricevuto text o encrypted_content, quindi il comportamento della cache è identico per entrambe le varianti di risultato.

Caching lato advisor

Imposta caching sulla definizione dello strumento per abilitare il caching del 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-7",
        "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 advisor scrive una voce di cache; la chiamata successiva legge fino a quel punto e paga solo per il delta. Vedrai cache_read_input_tokens diventare diverso da zero nelle iterazioni advisor_message seconda e successive.

Quando abilitarlo: Il costo della scrittura della cache è superiore ai risparmi delle letture quando l'advisor viene chiamato due o meno volte per conversazione. Il caching si pareggia approssimativamente a tre chiamate advisor e migliora da lì. Abilitalo per lunghi loop di agenti; mantienilo disattivato per attività brevi.

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

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-7",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

L'executor può cercare il web, chiamare l'advisor e usare i tuoi strumenti personalizzati nello stesso turno. Il piano dell'advisor può informare quali strumenti l'executor raggiunge dopo.

Migliori pratiche

Prompting per attività di codifica e agenti

Lo strumento advisor viene fornito con una descrizione incorporata che spinge l'executor a chiamarlo vicino all'inizio di attività complesse e quando incontra difficoltà. Per attività di ricerca, in genere non è necessario prompting aggiuntivo.

Su attività di codifica e agenti, l'advisor produce intelligenza superiore a costo simile quando riduce il numero totale di chiamate di strumenti e la lunghezza della conversazione. Due tempi guidano questo miglioramento:

1. Una prima chiamata advisor iniziale, dopo che poche letture esplorative sono nella trascrizione.
2. Per attività difficili, una chiamata advisor finale dopo che le scritture di file e gli output dei test sono nella trascrizione.

Se il tuo agente espone altri strumenti simili a planner (ad esempio, uno strumento di elenco di cose da fare), chiedi al modello di chiamare l'advisor prima di questi strumenti in modo che il piano dell'advisor si riversi in essi. Il prompt di sistema suggerito di seguito rinforza il modello di chiamata iniziale; aggiungi la tua frase di imbuto che punta a qualsiasi strumento planner che il tuo agente espone.

Prompt di sistema suggerito per attività di codifica

Per attività di codifica in cui desideri tempi advisor coerenti e circa due o tre chiamate per attività, anteponi i seguenti blocchi al prompt di sistema dell'executor prima di qualsiasi altra frase che menzioni l'advisor. Sulle valutazioni di codifica interne questo modello ha prodotto l'intelligenza più alta a costo quasi Sonnet.

Guida ai tempi:

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 (posizionare direttamente dopo il blocco dei tempi):

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.

Riduzione della lunghezza dell'output dell'advisor

L'output dell'advisor è il principale driver di costo dell'advisor. Per ridurre quel costo, anteponi una singola istruzione di concisione al prompt di sistema prima di qualsiasi altra frase che menzioni l'advisor. Nei test interni, la seguente riga ha ridotto i token di output totali dell'advisor di circa il 35-45 percento senza cambiare la frequenza delle chiamate:

The advisor should respond in under 100 words and use enumerated steps, not explanations.

Abbina questo con il blocco dei tempi sopra per il miglior compromesso tra costo e qualità.

Abbinamento con impostazioni di sforzo

Per attività di codifica, abbinare un executor Sonnet a sforzo medio con un advisor Opus raggiunge intelligenza paragonabile a Sonnet a sforzo predefinito, a costo inferiore. Per massima intelligenza, mantieni l'executor a sforzo predefinito.

Controllo dei costi

• Per budget a livello di conversazione, conta le chiamate advisor lato client. Quando raggiungi il tuo limite, rimuovi lo strumento advisor da tools e rimuovi tutti i blocchi advisor_tool_result dalla tua cronologia dei messaggi per evitare un 400 invalid_request_error.
• Abilita caching solo per conversazioni in cui prevedi tre o più chiamate advisor.

Limitazioni

• L'output dell'advisor non esegue lo streaming. Aspettati una pausa nello stream mentre la sub-inferenza funziona.
• Nessun limite incorporato a livello di conversazione sulle chiamate advisor. Traccia e limitale lato client.
• max_tokens si applica solo all'output dell'executor. Non limita i token dell'advisor.
• Anthropic Priority Tier è onorato per modello. Priority Tier sul modello executor non si estende all'advisor; hai bisogno di Priority Tier sul modello advisor specificamente.