---
title: Strumento advisor
url: https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool
description: Abbina un modello executor più veloce a un modello advisor più intelligente che fornisce indicazioni strategiche durante la generazione.
---
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](https://platform.claude.com/docs/it/about-claude/models/optimizing-for-cost-and-intelligence).
```mermaid
sequenceDiagram
accTitle: How the executor model consults the advisor model
accDescr: Your application sends a request with the advisor tool to the executor model, which begins the task. The executor emits a server_tool_use block, and Anthropic runs the advisor model server-side. The advisor reads the full transcript and returns strategic guidance in an advisor_tool_result. The executor continues, informed by the advice, and returns the response to your application.
participant U as Your application
participant E as Executor model
participant A as Advisor model
U->>E: Request with advisor tool
note over E: Executor begins the task
E->>A: server_tool_use (server-side)
note over A: Reads the full transcript,
returns strategic guidance
A-->>E: advisor_tool_result
note over E: Executor continues,
informed by the advice
E-->>U: Response
```
Per scoprire come la "zero data retention" (conservazione zero dei dati), o ZDR, si applica a questa funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
## 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
Lo strumento advisor è in beta. Includi l'header beta `advisor-tool-2026-03-01` nelle tue richieste.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: advisor-tool-2026-03-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 4096,
"tools": [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5"
}
],
"messages": [{
"role": "user",
"content": "Build a concurrent worker pool in Go with graceful shutdown."
}]
}'
```
```bash CLI
ant beta:messages create --beta advisor-tool-2026-03-01 <<'YAML'
model: claude-sonnet-5
max_tokens: 4096
tools:
- type: advisor_20260301
name: advisor
model: claude-opus-5
messages:
- role: user
content: Build a concurrent worker pool in Go with graceful shutdown.
YAML
```
```python Python
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await 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."
}
]
});
console.log(response);
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var client = new AnthropicClient();
var parameters = new MessageCreateParams
{
Model = Messages::Model.ClaudeSonnet5,
MaxTokens = 4096,
Tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301
{
Model = Messages::Model.ClaudeOpus5
}
},
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = "Build a concurrent worker pool in Go with graceful shutdown."
}
],
Betas = ["advisor-tool-2026-03-01"]
};
var response = await client.Beta.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeSonnet5,
MaxTokens: 4096,
Tools: []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a concurrent worker pool in Go with graceful shutdown.")),
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5)
.maxTokens(4096L)
.addTool(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.build())
.addUserMessage("Build a concurrent worker pool in Go with graceful shutdown.")
.addBeta("advisor-tool-2026-03-01")
.build();
BetaMessage response = client.beta().messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: [
[
'role' => 'user',
'content' => 'Build a concurrent worker pool in Go with graceful shutdown.',
],
],
model: 'claude-sonnet-5',
tools: [
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-5',
],
],
betas: ['advisor-tool-2026-03-01'],
);
echo $response;
```
```ruby Ruby
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-sonnet-5",
max_tokens: 4096,
tools: [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5"
}
],
messages: [
{
role: "user",
content: "Build a concurrent worker pool in Go with graceful shutdown."
}
],
betas: ["advisor-tool-2026-03-01"]
)
puts 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#result-variants) per confrontare le due forme e sapere quali modelli advisor restituiscono ciascuna, e [Compatibilità dei modelli](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#model-compatibility) 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`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools) 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn)).
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
| Parametro | Tipo | Predefinito | Descrizione |
| ------------ | -------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | *obbligatorio* | Deve essere `"advisor_20260301"`. |
| `name` | string | *obbligatorio* | Deve essere `"advisor"`. |
| `model` | string | *obbligatorio* | L'ID del modello advisor, ad esempio claude-opus-5. La sotto-inferenza viene fatturata alle tariffe di questo modello. |
| `max_uses` | integer | illimitato | Numero massimo di chiamate all'advisor consentite in una singola richiesta. Una volta che l'executor raggiunge questo limite, le ulteriori chiamate all'advisor restituiscono un `advisor_tool_result_error` con `error_code: "max_uses_exceeded"` e l'executor prosegue senza ulteriori consigli. Si tratta di un limite per richiesta, non per conversazione. Consulta [Controllo dei costi](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#cost-control) per i limiti a livello di conversazione. |
| `max_tokens` | integer | limite di output del modello advisor | Limita l'output totale dell'advisor (ragionamento più testo) per chiamata. Minimo 1024. Consulta [Limitare l'output dell'advisor](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#capping-advisor-output). |
| `caching` | object \| null | `null` (disattivato) | Abilita la [cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching) per la trascrizione dell'advisor tra le chiamate all'interno di una conversazione. Consulta [Cache dei prompt dell'advisor](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#advisor-prompt-caching). |
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](https://platform.claude.com/docs/it/build-with-claude/structured-outputs)). Consulta il [Riferimento degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#tool-definition-properties) 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#quick-start) usa Claude Opus 5, che restituisce invece la variante crittografata `advisor_redacted_result`; consulta [Varianti del risultato](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#result-variants) per confrontare le due forme.
```json
{
"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:
| Variante | Campi | Restituita quando |
| ------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
| `advisor_result` | `text`, `stop_reason` | Il modello advisor restituisce testo in chiaro (ad esempio, Claude Opus 4.8). |
| `advisor_redacted_result` | `encrypted_content`, `stop_reason` | Il modello advisor restituisce output crittografato. |
Gli advisor Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Fable 5, Claude Mythos 5 e Claude Haiku 5.5 restituiscono la variante crittografata `advisor_redacted_result`. Ogni altro modello advisor nella [tabella di compatibilità](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#model-compatibility) restituisce la variante in chiaro `advisor_result`. Per leggere il testo del consiglio nelle tue risposte, usa un advisor che restituisce testo in chiaro, come `claude-opus-4-8`, laddove la riga del tuo executor nella [tabella di compatibilità](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#model-compatibility) ne elenchi uno. Gli executor Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Fable 5 e Claude Mythos 5 si abbinano solo ad advisor che restituiscono la forma crittografata, quindi con questi executor il testo del consiglio non è leggibile nella risposta.
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:
```json
{
"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:
```json
{
"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`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#capping-advisor-output) 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`](https://platform.claude.com/docs/it/build-with-claude/handling-stop-reasons) 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:
```json
{
"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.
| `error_code` | Significato |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_uses_exceeded` | La richiesta ha raggiunto il limite `max_uses` impostato nella definizione dello strumento. Le ulteriori chiamate all'advisor nella stessa richiesta restituiscono questo errore. |
| `too_many_requests` | La sotto-inferenza dell'advisor è stata soggetta a limite di velocità. |
| `overloaded` | La sotto-inferenza dell'advisor ha raggiunto i limiti di capacità. |
| `prompt_too_long` | La trascrizione ha superato la "context window" (finestra di contesto) del modello advisor. |
| `execution_time_exceeded` | La sotto-inferenza dell'advisor è andata in timeout. |
| `model_not_found` | Il modello advisor configurato non è disponibile. |
| `unavailable` | Qualsiasi altro errore dell'advisor. |
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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#result-variants)). Il meccanismo è identico per qualsiasi modello advisor.
```python Python
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,
)
```
```typescript TypeScript
const client = new Anthropic();
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5"
}
];
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{
role: "user",
content: "Build a concurrent worker pool in Go with graceful shutdown."
}
];
const response = await client.beta.messages.create({
model: "claude-sonnet-5",
max_tokens: 1024,
betas: ["advisor-tool-2026-03-01"],
tools,
messages
});
// Aggiungi l'intero contenuto della risposta, inclusi eventuali blocchi advisor_tool_result
messages.push({ role: "assistant", content: response.content });
// Continua la conversazione
messages.push({ role: "user", content: "Now add a max-in-flight limit of 10." });
const followUp = await client.beta.messages.create({
model: "claude-sonnet-5",
max_tokens: 1024,
betas: ["advisor-tool-2026-03-01"],
tools,
messages
});
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var client = new AnthropicClient();
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 }
};
var messages = new List
{
new() { Role = Role.User, Content = "Build a concurrent worker pool in Go with graceful shutdown." }
};
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeSonnet5,
MaxTokens = 1024,
Tools = tools,
Messages = messages,
Betas = ["advisor-tool-2026-03-01"]
});
// Aggiungi l'intero contenuto della risposta, inclusi eventuali blocchi advisor_tool_result
messages.Add(new BetaMessageParam
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
// Continua la conversazione
messages.Add(new BetaMessageParam { Role = Role.User, Content = "Now add a max-in-flight limit of 10." });
var followUp = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeSonnet5,
MaxTokens = 1024,
Tools = tools,
Messages = messages,
Betas = ["advisor-tool-2026-03-01"]
});
```
```go Go
client := anthropic.NewClient()
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
}
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a concurrent worker pool in Go with graceful shutdown.")),
}
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeSonnet5,
MaxTokens: 1024,
Tools: tools,
Messages: messages,
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
// Aggiungi l'intero contenuto della risposta, inclusi eventuali blocchi advisor_tool_result.
messages = append(messages, response.ToParam())
// Continua la conversazione
messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Now add a max-in-flight limit of 10.")))
response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeSonnet5,
MaxTokens: 1024,
Tools: tools,
Messages: messages,
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaContentBlock;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaMessageParam;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(
BetaAdvisorTool20260301.builder().model(Model.CLAUDE_OPUS_5).build()));
List messages = new ArrayList<>();
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content("Build a concurrent worker pool in Go with graceful shutdown.")
.build());
BetaMessage response = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5)
.maxTokens(1024L)
.tools(tools)
.messages(messages)
.addBeta("advisor-tool-2026-03-01")
.build());
// Aggiungi l'intero contenuto della risposta, inclusi eventuali blocchi advisor_tool_result
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.ASSISTANT)
.contentOfBetaContentBlockParams(
response.content().stream().map(BetaContentBlock::toParam).toList())
.build());
// Continua la conversazione
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content("Now add a max-in-flight limit of 10.")
.build());
BetaMessage followUp = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5)
.maxTokens(1024L)
.tools(tools)
.messages(messages)
.addBeta("advisor-tool-2026-03-01")
.build());
}
```
```php PHP
$client = new Client();
$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(
maxTokens: 1024,
messages: $messages,
model: 'claude-sonnet-5',
tools: $tools,
betas: ['advisor-tool-2026-03-01'],
);
// Aggiungi l'intero contenuto della risposta, inclusi eventuali blocchi advisor_tool_result
$messages[] = ['role' => 'assistant', 'content' => $response->content];
// Continua la conversazione
$messages[] = ['role' => 'user', 'content' => 'Now add a max-in-flight limit of 10.'];
$response = $client->beta->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-sonnet-5',
tools: $tools,
betas: ['advisor-tool-2026-03-01'],
);
```
```ruby Ruby
client = Anthropic::Client.new
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,
tools: tools,
messages: messages,
betas: ["advisor-tool-2026-03-01"]
)
# Aggiungi l'intero contenuto della risposta, inclusi eventuali blocchi advisor_tool_result
messages << { role: "assistant", content: response.content }
# Continua la conversazione
messages << { role: "user", content: "Now add a max-in-flight limit of 10." }
response = client.beta.messages.create(
model: "claude-sonnet-5",
max_tokens: 1024,
tools: tools,
messages: messages,
betas: ["advisor-tool-2026-03-01"]
)
```
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.
Lo strumento advisor non ha un limite integrato a livello di conversazione. Per limitare le chiamate all'advisor nell'arco di una conversazione, contale lato client. Quando raggiungi il tuo tetto, rimuovi lo strumento advisor dal tuo array `tools`. Non è necessario eliminare i blocchi `advisor_tool_result` dalla cronologia dei messaggi.
### 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn).
### 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.
```python Python
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})
```
```typescript TypeScript
const client = new Anthropic();
const NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet
const 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.";
const MAX_TURNS = 10; // agent loop cap
function runYourTools(
content: Anthropic.Beta.Messages.BetaContentBlock[]
): Anthropic.Beta.Messages.BetaToolResultBlockParam[] {
// Sostituisci con il tuo dispatch degli strumenti. Restituisce un blocco tool_result per ogni blocco tool_use.
return content
.filter((block) => block.type === "tool_use")
.map((block) => ({
type: "tool_result" as const,
tool_use_id: block.id,
content: "Replace with your tool output."
}));
}
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{ type: "advisor_20260301", name: "advisor", model: "claude-opus-5" }
// ... i tuoi altri strumenti
];
const task = "Build a concurrent worker pool in Go with graceful shutdown.";
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [{ role: "user", content: task }];
let advisorCalled = false;
for (let turn = 1; turn <= MAX_TURNS; turn++) {
const response = await client.beta.messages.create({
model: "claude-haiku-5-5",
max_tokens: 4096,
betas: ["advisor-tool-2026-03-01"],
tools,
messages
});
messages.push({ role: "assistant", content: response.content });
advisorCalled =
advisorCalled ||
response.content.some(
(block) => block.type === "server_tool_use" && block.name === "advisor"
);
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)
}
const results = runYourTools(response.content); // list of tool_result blocks
if (results.length > 0) {
messages.push({ 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 && !advisorCalled) {
messages.push({ role: "user", content: NUDGE_TEXT });
}
}
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var client = new AnthropicClient();
const int NudgeTurn = 2; // inject before this assistant turn if no advisor call yet
const string NudgeText =
"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.";
const int MaxTurns = 10; // agent loop cap
// Sostituisci con il tuo dispatch degli strumenti. Restituisce un blocco tool_result per ogni blocco tool_use.
List RunYourTools(IReadOnlyList content)
{
List results = [];
foreach (var block in content)
{
if (block.TryPickToolUse(out var toolUse))
{
results.Add(new BetaToolResultBlockParam
{
ToolUseID = toolUse.ID,
Content = "Replace with your tool output."
});
}
}
return results;
}
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 }
// ... i tuoi altri strumenti
};
var task = "Build a concurrent worker pool in Go with graceful shutdown.";
var messages = new List { new() { Role = Role.User, Content = task } };
var advisorCalled = false;
for (var turn = 1; turn <= MaxTurns; turn++)
{
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeHaiku5_5,
MaxTokens = 4096,
Tools = tools,
Messages = messages,
Betas = ["advisor-tool-2026-03-01"]
});
messages.Add(new BetaMessageParam
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
advisorCalled =
advisorCalled
|| response.Content.Any(block =>
block.TryPickServerToolUse(out var serverToolUse)
&& serverToolUse.Name.Value() == Name.Advisor
);
if (response.StopReason == BetaStopReason.PauseTurn)
{
continue; // server tool pending; re-send to let the API complete it
}
if (response.StopReason != BetaStopReason.ToolUse)
{
break; // end_turn, or a stop such as max_tokens that needs handling (see below)
}
var results = RunYourTools(response.Content); // list of tool_result blocks
if (results.Count > 0)
{
messages.Add(new BetaMessageParam { Role = Role.User, Content = results });
}
// Salta questo passaggio se il tuo prompt di sistema indica già al modello di effettuare chiamate con parsimonia.
if (turn == NudgeTurn - 1 && !advisorCalled)
{
messages.Add(new BetaMessageParam { Role = Role.User, Content = NudgeText });
}
}
```
```go Go
const (
nudgeTurn = 2 // inject before this assistant turn if no advisor call yet
nudgeText = "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."
maxTurns = 10 // agent loop cap
)
// Sostituisci con il tuo dispatch degli strumenti. Restituisce un blocco tool_result per ogni blocco tool_use.
func runYourTools(content []anthropic.BetaContentBlockUnion) []anthropic.BetaContentBlockParamUnion {
var results []anthropic.BetaContentBlockParamUnion
for _, block := range content {
if block.Type == "tool_use" {
results = append(results, anthropic.NewBetaToolResultBlock(block.ID, "Replace with your tool output.", false))
}
}
return results
}
func main() {
client := anthropic.NewClient()
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
// ... i tuoi altri strumenti
}
task := "Build a concurrent worker pool in Go with graceful shutdown."
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(task)),
}
advisorCalled := false
for turn := 1; turn <= maxTurns; turn++ {
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeHaiku5_5,
MaxTokens: 4096,
Tools: tools,
Messages: messages,
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
messages = append(messages, response.ToParam())
for _, block := range response.Content {
if block.Type == "server_tool_use" && block.Name == "advisor" {
advisorCalled = true
}
}
if response.StopReason == anthropic.BetaStopReasonPauseTurn {
continue // server tool pending; re-send to let the API complete it
}
if response.StopReason != anthropic.BetaStopReasonToolUse {
break // end_turn, or a stop such as max_tokens that needs handling (see below)
}
results := runYourTools(response.Content) // list of tool_result blocks
if len(results) > 0 {
messages = append(messages, anthropic.BetaMessageParam{
Role: anthropic.BetaMessageParamRoleUser,
Content: results,
})
}
// Salta questo passaggio se il tuo prompt di sistema indica già al modello di effettuare chiamate con parsimonia.
if turn == nudgeTurn-1 && !advisorCalled {
messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(nudgeText)))
}
}
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaContentBlock;
import com.anthropic.models.beta.messages.BetaContentBlockParam;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaMessageParam;
import com.anthropic.models.beta.messages.BetaServerToolUseBlock;
import com.anthropic.models.beta.messages.BetaStopReason;
import com.anthropic.models.beta.messages.BetaToolResultBlockParam;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
static final int NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet
static final String 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.";
static final int MAX_TURNS = 10; // agent loop cap
// Sostituisci con il tuo dispatch degli strumenti. Restituisce un blocco tool_result per ogni blocco tool_use.
List runYourTools(List content) {
List results = new ArrayList<>();
for (BetaContentBlock block : content) {
if (block.isToolUse()) {
results.add(BetaContentBlockParam.ofToolResult(
BetaToolResultBlockParam.builder()
.toolUseId(block.asToolUse().id())
.content("Replace with your tool output.")
.build()));
}
}
return results;
}
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(
BetaAdvisorTool20260301.builder().model(Model.CLAUDE_OPUS_5).build())
// ... i tuoi altri strumenti
);
String task = "Build a concurrent worker pool in Go with graceful shutdown.";
List messages = new ArrayList<>();
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content(task)
.build());
boolean advisorCalled = false;
for (int turn = 1; turn <= MAX_TURNS; turn++) {
BetaMessage response = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_HAIKU_5_5)
.maxTokens(4096L)
.tools(tools)
.messages(messages)
.addBeta("advisor-tool-2026-03-01")
.build());
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.ASSISTANT)
.contentOfBetaContentBlockParams(
response.content().stream().map(BetaContentBlock::toParam).toList())
.build());
advisorCalled = advisorCalled
|| response.content().stream().anyMatch(block ->
block.isServerToolUse()
&& block.asServerToolUse().name().equals(BetaServerToolUseBlock.Name.ADVISOR));
BetaStopReason stopReason = response.stopReason().orElse(null);
if (BetaStopReason.PAUSE_TURN.equals(stopReason)) {
continue; // server tool pending; re-send to let the API complete it
}
if (!BetaStopReason.TOOL_USE.equals(stopReason)) {
break; // end_turn, or a stop such as max_tokens that needs handling (see below)
}
List results = runYourTools(response.content()); // list of tool_result blocks
if (!results.isEmpty()) {
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.contentOfBetaContentBlockParams(results)
.build());
}
// Salta questo passaggio se il tuo prompt di sistema indica già al modello di effettuare chiamate con parsimonia.
if (turn == NUDGE_TURN - 1 && !advisorCalled) {
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content(NUDGE_TEXT)
.build());
}
}
}
```
```php PHP
$client = new Client();
const NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet
const 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.";
const MAX_TURNS = 10; // agent loop cap
// Sostituisci con il tuo dispatch degli strumenti. Restituisce un blocco tool_result per ogni blocco tool_use.
function runYourTools(array $content): array
{
$results = [];
foreach ($content as $block) {
if ($block->type === 'tool_use') {
$results[] = [
'type' => 'tool_result',
'tool_use_id' => $block->id,
'content' => 'Replace with your tool output.',
];
}
}
return $results;
}
$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]];
$advisorCalled = false;
for ($turn = 1; $turn <= MAX_TURNS; $turn++) {
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-haiku-5-5',
tools: $tools,
betas: ['advisor-tool-2026-03-01'],
);
$messages[] = ['role' => 'assistant', 'content' => $response->content];
foreach ($response->content as $block) {
if ($block->type === 'server_tool_use' && $block->name === 'advisor') {
$advisorCalled = true;
}
}
if ($response->stopReason === 'pause_turn') {
continue; // server tool pending; re-send to let the API complete it
}
if ($response->stopReason !== 'tool_use') {
break; // end_turn, or a stop such as max_tokens that needs handling (see below)
}
$results = runYourTools($response->content); // list of tool_result blocks
if ($results !== []) {
$messages[] = ['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 && !$advisorCalled) {
$messages[] = ['role' => 'user', 'content' => NUDGE_TEXT];
}
}
```
```ruby Ruby
client = Anthropic::Client.new
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
# Sostituisci con il tuo dispatch degli strumenti. Restituisce un blocco tool_result per ogni blocco tool_use.
def run_your_tools(content)
content.filter_map do |block|
next unless block.type == :tool_use
{ type: "tool_result", tool_use_id: block.id, content: "Replace with your tool output." }
end
end
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
(1..MAX_TURNS).each do |turn|
response = client.beta.messages.create(
model: "claude-haiku-5-5",
max_tokens: 4096,
tools: tools,
messages: messages,
betas: ["advisor-tool-2026-03-01"]
)
messages << { role: "assistant", content: response.content }
advisor_called ||= response.content.any? do |block|
block.type == :server_tool_use && block.name == :advisor
end
next if response.stop_reason == :pause_turn # server tool pending; re-send to let the API complete it
break unless response.stop_reason == :tool_use # 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
messages << { role: "user", content: results } unless results.empty?
# Salta questo passaggio se il tuo prompt di sistema indica già al modello di effettuare chiamate con parsimonia.
messages << { role: "user", content: NUDGE_TEXT } if turn == NUDGE_TURN - 1 && !advisor_called
end
```
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](https://platform.claude.com/docs/it/build-with-claude/handling-stop-reasons#max-tokens). Quando quel turno non contiene alcun blocco `tool_use`, puoi invece mantenerlo e [continuare la risposta](https://platform.claude.com/docs/it/build-with-claude/handling-stop-reasons#ensuring-complete-responses) con un nuovo messaggio utente. Reinviare il turno dell'assistente troncato come ultimo messaggio costituisce un [prefill](https://platform.claude.com/docs/it/api/errors#prefill-not-supported), 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/define-tools#forcing-tool-use). 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[]`:
```json
{
"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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#capping-advisor-output). I token dell'advisor inoltre non attingono ad alcun [budget del compito](https://platform.claude.com/docs/it/build-with-claude/task-budgets) applicato all'executor.
Il [Priority Tier](https://platform.claude.com/docs/it/api/service-tiers) 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:
```python Python
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
"caching": {"type": "ephemeral", "ttl": "5m"},
}
]
```
```typescript TypeScript
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5",
caching: { type: "ephemeral", ttl: "5m" }
}
];
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301
{
Model = Messages::Model.ClaudeOpus5,
Caching = new BetaCacheControlEphemeral { Ttl = Ttl.Ttl5m }
}
};
```
```go Go
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
Caching: anthropic.BetaCacheControlEphemeralParam{TTL: anthropic.BetaCacheControlEphemeralTTLTTL5m},
}},
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaCacheControlEphemeral;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.messages.Model;
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.caching(BetaCacheControlEphemeral.builder()
.ttl(BetaCacheControlEphemeral.Ttl.TTL_5M)
.build())
.build()));
```
```php PHP
$tools = [
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-5',
'caching' => ['type' => 'ephemeral', 'ttl' => '5m'],
],
];
```
```ruby Ruby
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.
[`clear_thinking`](https://platform.claude.com/docs/it/build-with-claude/context-editing) con un valore `keep` diverso da `"all"` sposta la trascrizione citata dell'advisor a ogni turno, causando cache miss lato advisor. Si tratta solo di un peggioramento dei costi. La qualità del consiglio non ne risente. Quando il ragionamento è attivo senza una configurazione esplicita di `clear_thinking`, l'API usa come predefinito `keep: {type: "thinking_turns", value: 1}`, che attiva questo comportamento (il valore predefinito sui modelli Opus e Sonnet precedenti e sui modelli Haiku fino a Claude Haiku 4.5; su Claude Opus 4.5 e i modelli Opus successivi, Claude Sonnet 4.6 e i modelli Sonnet successivi, e Claude Haiku 5.5, il valore predefinito è mantenere tutti i turni). Imposta `keep: "all"` per preservare la stabilità della cache dell'advisor.
## Combinazione con altri strumenti
Lo strumento advisor si combina con altri strumenti lato server e lato client. Aggiungili tutti allo stesso array `tools`:
```python Python
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"}},
},
},
]
```
```typescript TypeScript
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
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" } }
}
}
];
```
```csharp C#
using System.Text.Json;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var tools = new BetaToolUnion[]
{
new BetaWebSearchTool20250305 { MaxUses = 5 },
new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 },
new BetaTool
{
Name = "run_bash",
Description = "Run a bash command",
InputSchema = new()
{
Properties = new Dictionary
{
["command"] = JsonSerializer.SerializeToElement(new { type = "string" })
}
}
}
};
```
```go Go
tools := []anthropic.BetaToolUnionParam{
{OfWebSearchTool20250305: &anthropic.BetaWebSearchTool20250305Param{
MaxUses: anthropic.Int(5),
}},
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
{OfTool: &anthropic.BetaToolParam{
Name: "run_bash",
Description: anthropic.String("Run a bash command"),
InputSchema: anthropic.BetaToolInputSchemaParam{
Properties: map[string]any{
"command": map[string]any{"type": "string"},
},
},
}},
}
```
```java Java
import com.anthropic.core.JsonValue;
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaTool;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.beta.messages.BetaWebSearchTool20250305;
import com.anthropic.models.messages.Model;
List tools = List.of(
BetaToolUnion.ofWebSearchTool20250305(BetaWebSearchTool20250305.builder()
.maxUses(5L)
.build()),
BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.build()),
BetaToolUnion.ofBetaTool(BetaTool.builder()
.name("run_bash")
.description("Run a bash command")
.inputSchema(BetaTool.InputSchema.builder()
.properties(JsonValue.from(Map.of(
"command", Map.of("type", "string"))))
.build())
.build()));
```
```php PHP
$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']],
],
],
];
```
```ruby Ruby
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.
| Funzionalità | Interazione |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Elaborazione batch](https://platform.claude.com/docs/it/build-with-claude/batch-processing) | Supportata. `usage.iterations` viene riportato per ogni elemento. |
| [Conteggio dei token](https://platform.claude.com/docs/it/build-with-claude/token-counting) | Restituisce solo i token di input della prima iterazione dell'executor. Per una stima approssimativa dell'advisor, chiama `client.beta.messages.count_tokens()` (typescript: `client.beta.messages.countTokens()`; go, csharp: `client.Beta.Messages.CountTokens()`; java: `client.beta().messages().countTokens()`; php: `$client->beta->messages->countTokens()`; cli: `ant beta:messages count-tokens`; curl: `POST /v1/messages/count_tokens`) con `model` impostato sul modello advisor e gli stessi messaggi. |
| [Modifica del contesto](https://platform.claude.com/docs/it/build-with-claude/context-editing) | `clear_tool_uses` non è pienamente compatibile con i blocchi dello strumento advisor. Con `clear_thinking`, consulta l'avviso sulla cache riportato in precedenza. |
| `pause_turn` | Una chiamata all'advisor rimasta in sospeso termina la risposta con `stop_reason: "pause_turn"` e un blocco `server_tool_use` senza risultato quando nessun blocco `tool_use` del client è in attesa del tuo risultato nello stesso turno. L'advisor viene eseguito alla ripresa. Se l'executor ha chiamato anche uno dei tuoi strumenti in quel turno, la risposta termina invece con `stop_reason: "tool_use"`, e la chiamata all'advisor in sospeso viene eseguita all'inizio della tua richiesta successiva, dopo che hai inviato i blocchi `tool_result`. Consulta [Riprendere un turno in pausa](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn), [Combinare strumenti server e strumenti client in un unico turno](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn) e [Strumenti server](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn). |
## 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks) 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:
```text wrap
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):
```text wrap
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:
```text wrap
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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks), 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:
```text wrap
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:
```text wrap
(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.
Nei test di Anthropic questa riga ha anche aumentato la frequenza con cui l'executor consulta l'advisor, ma l'effetto netto è stato comunque un costo totale inferiore (più consultazioni, ciascuna più breve).
Abbina questo approccio alle indicazioni sulla tempistica in [Prompt di sistema suggerito per i compiti di programmazione](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks) (o al [blocco alternativo per Haiku](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#alternative-system-prompt-for-haiku-on-coding-workloads), 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#capping-advisor-output).
### Limitare l'output dell'advisor
Imposta `max_tokens` nella definizione dello strumento per limitare l'output totale dell'advisor (ragionamento più testo) per chiamata:
```python Python
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
"max_tokens": 2048,
}
]
```
```typescript TypeScript
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5",
max_tokens: 2048
}
];
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301
{
Model = Messages::Model.ClaudeOpus5,
MaxTokens = 2048
}
};
```
```go Go
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: anthropic.Int(2048),
}},
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.messages.Model;
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(2048L)
.build()));
```
```php PHP
$tools = [
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-5',
'max_tokens' => 2048,
],
];
```
```ruby Ruby
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.
| `max_tokens` | Token medi di output dell'advisor | Chiamate troncate |
| ------------- | --------------------------------- | ----------------- |
| non impostato | \~4.200-5.900 | n/d |
| 2048 | \~630-840 | \~0% |
| 1024 | \~370-480 | \~10% |
I compiti di ragionamento difficili producono un output dell'advisor sostanzialmente più lungo rispetto ai [tipici 1.400-1.800 token](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#usage-and-billing) 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#result-variants), 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.
```json
{
"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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#trimming-advisor-output-length), `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](https://platform.claude.com/docs/it/build-with-claude/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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#multi-turn-conversations)).
* 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.
| Modelli executor | Modelli advisor |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Haiku 4.5 (claude-haiku-4-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Haiku 5.5 (claude-haiku-5-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Sonnet 4.6 (claude-sonnet-4-6) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Sonnet 5 (claude-sonnet-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Sonnet 5.5 (claude-sonnet-5-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Sonnet 5.5 (claude-sonnet-5-5) |
| Claude Opus 4.6 (claude-opus-4-6) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Opus 4.7 (claude-opus-4-7) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5) |
| Claude Opus 4.8 (claude-opus-4-8) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5) |
| Claude Opus 5 (claude-opus-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Opus 5.5 (claude-opus-5-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Fable 5 (claude-fable-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Mythos 5 (claude-mythos-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Fable 5.1 (claude-fable-5-1) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1) |
| Claude Mythos 5.1 (claude-mythos-5-1) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1) |
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](https://platform.claude.com/docs/it/build-with-claude/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](https://platform.claude.com/docs/it/managed-agents/overview) 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](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
## Passaggi successivi
Archivia e recupera informazioni tra le conversazioni con una directory di memoria lato client.
Lavora con gli strumenti eseguiti da Anthropic: blocchi server\_tool\_use, continuazione con pause\_turn e filtraggio dei domini.
Elenco degli strumenti forniti da Anthropic e riferimento per le proprietà opzionali della definizione degli strumenti.
Controlla quanti token Claude utilizza nelle risposte con il parametro effort, bilanciando la completezza delle risposte e l'efficienza nell'uso dei token.