Effort tuning: 5 livelli, default per modello e la trappola della cache
Il 22 luglio 2026 Anthropic ha portato effort dentro la configurazione modello dei Claude Managed Agents, chiudendo il cerchio su un controllo che la Messages API ha silenziosamente esteso a cinque livelli. Se stai ancora copiando effort="high" al livello superiore di messages.create da un post di inizio 2026, la tua richiesta sembra valida ma Claude potrebbe non stare onorando il campo che pensi — il parametro ora vive dentro output_config e l'API applica solo i livelli documentati sulla scheda del modello.
Questa è la guida pratica al tuning: dove va davvero effort in una richiesta, cosa fanno realmente i cinque livelli (cambiano il numero di tool call, non solo la profondità del thinking), i default per modello che ti sorprenderanno e l'unico gotcha che fa esplodere la spesa in silenzio — cambiare effort a metà conversazione invalida la prompt cache.
- Metti il campo effort nel posto giusto — dentro output_config sulla Messages API, nell'oggetto model sui Managed Agents, via /effort o CLAUDE_CODE_EFFORT_LEVEL in Claude Code
- Scegli un livello di partenza per modello — high è il default dell'API ma l'effort consigliato di partenza varia per modello (Sonnet 5 high, Sonnet 4.6 medium, Opus 4.7/4.8 xhigh, Fable 5 high)
- Capisci che effort influenza TUTTI i token — testo, tool call e (quando attivo) thinking — quindi abbassare effort riduce il numero di tool call, non solo la verbosità
- Evita la trappola della cache — variare effort dentro una conversazione invalida la prompt caching e può raddoppiare la bolletta in silenzio
- Conosci la superficie effort di Claude Code — /effort, ultrathink (un solo turno), ultracode (xhigh + permesso multiagent permanente), override via env CLAUDE_CODE_EFFORT_LEVEL
I cinque livelli (e dove entra "ultracode")
La scala di effort al 22 luglio 2026 ha cinque valori accettati dall'API:
| Livello | Cosa fa | Quando usarlo |
|---|---|---|
low | Massima efficienza. Risparmio di token significativo con qualche riduzione di capacità. Meno tool call, conferme sintetiche, niente preamboli. | Classificazioni semplici, workload ad alto volume, chat, UX sensibili alla latenza, subagenti con lavoro circoscritto |
medium | Bilanciato. Risparmio moderato di token rispetto a high. | Task agentici che vogliono velocità + costo + qualità bilanciati; step-down cost-conscious da high |
high | Alta capacità. Equivalente a omettere il parametro. | Reasoning complesso, coding difficile, task agentici dove la qualità conta più della velocità |
xhigh | Capacità estesa per lavoro long-horizon. Aspettati un uso di token nettamente superiore a high. | Task agentici e di coding lunghi (30+ min), budget da milioni di token, refactor deep multi-file |
max | Capacità massima assoluta, nessun vincolo sul consumo di token. | Solo problemi genuinamente frontier. Può fare overthinking su task di structured output. |
max è universale tra i modelli che supportano effort. xhigh è più recente ed è supportato solo su Fable 5, Mythos 5, Opus 4.8, Opus 4.7 e Sonnet 5. I modelli effort-capable più vecchi (Sonnet 4.6, Opus 4.6, Opus 4.5) capiscono max ma non xhigh.
- Impostare effort='high' produce esattamente lo stesso comportamento che ometterlo — non farlo 'per essere esplicito' in una conversazione cachata, perché scrivere il campo su alcune richieste e non su altre invalida la cache.
- 'ultracode' non è un sesto livello. È xhigh + un permesso permanente per Claude Code di lanciare workflow multiagent, concesso via mid-conversation system message. L'API accetta cinque valori.
La struttura del campo che la maggior parte dei blog post sbaglia
Le trattazioni di inizio 2026 del parametro effort mostrano un campo top-level:
# WRONG on current models — silently ignored or 400
client.messages.create(
model="claude-opus-4-8",
effort="medium",
...
)
L'API attuale mette effort dentro un oggetto output_config e lo passa come fratello di messages/model:
Posizione corretta di effort — Messages API
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
output_config={"effort": "medium"},
messages=[{
"role": "user",
"content": "Analyse the trade-offs between microservices and monoliths."
}],
)
print(response.content[0].text)Sui Claude Managed Agents (il cambio del 22 luglio 2026), effort va dentro l'oggetto model dell'agente al momento della creazione. La session non lo imposta — lo fa la versione dell'agente.
Posizione corretta di effort — Managed Agents (POST /v1/agents)
# Effort travels with the versioned agent config,
# not the per-run session. Every session pinned to
# this agent version runs at xhigh.
POST https://api.anthropic.com/v1/agents
{
"name": "code-reviewer",
"model": {
"id": "claude-opus-4-8",
"effort": "xhigh"
},
"system_prompt": "You review pull requests for security issues.",
"tools": [...],
"mcp_servers": [...]
}Effort non è un controllo del thinking
Questo è il secondo grande fraintendimento. Effort funziona che il thinking sia attivo o meno e cambia i token che Claude spende in parti della risposta diverse dal thinking:
- Tool call. Effort più basso → meno tool call. Claude combina le operazioni in singole chiamate, salta l'esplorazione opzionale e procede all'azione senza preamboli.
- Lunghezza del testo. Effort più basso → output più asciutto. Conferme sintetiche dopo le tool call invece di riepiloghi dettagliati. Meno commenti al codice.
- Profondità del thinking (quando thinking è attivo). Effort più basso → salta del tutto il thinking sui prompt facili; pensa comunque su quelli genuinamente difficili, ma di meno.
Quest'ultimo punto conta: a low, Claude penserà comunque su un problema di dimostrazione, perché il task lo richiede. Effort è un segnale comportamentale, non un budget stretto di token. Non aspettarti un tetto rigido.
Il parametro thinking e il parametro effort rispondono a domande diverse. thinking decide se Claude produce blocchi di thinking. effort decide quanto lavoro va in tutta la risposta — inclusi quanto spesso e quanto a fondo Claude pensa quando l'adaptive thinking è attivo. Passare effort="adaptive" è un errore comune; adaptive è una thinking mode, non un livello di effort.
Su Opus 4.5 — l'unico modello extended-thinking-only che supporta effort — imposti effort e budget_tokens insieme. Scegli il livello di effort per il tuo task, poi dimensiona il budget di token del thinking per la profondità di ragionamento. Ogni altro modello effort-capable usa adaptive thinking e non accetta budget_tokens.
Punti di partenza per modello che sorprendono i team
Il default dell'API è high su ogni modello che supporta il parametro. Ma l'effort iniziale consigliato da Anthropic varia per modello, e il disallineamento è dove i team sovra- o sotto-spendono.
- Sonnet 5 ha default high sia sull'API sia in Claude Code, e la raccomandazione coincide. Sali a xhigh solo per i task di coding e agentici più difficili. Scendi a medium come mossa di cost-saving — Sonnet 5 a medium è confrontabile con Sonnet 4.6 a high. Usa low per chat e workload non-coding sensibili alla latenza.
- Sonnet 4.6 ha default high ma la guida di Anthropic raccomanda medium come default bilanciato per la maggior parte delle applicazioni, coding agentico incluso. Imposta esplicitamente effort='medium' — altrimenti erediti high e paghi latenza che non hai chiesto.
- Il default è high ma la raccomandazione per coding e lavoro agentico è xhigh. Usa high come minimo per workload sensibili all'intelligenza. Scendi a medium solo quando le tue eval mostrano che la qualità regge. Riserva max ai problemi genuinamente frontier — sulla maggior parte dei workload max aggiunge costo significativo per piccoli guadagni di qualità e su task di structured output può fare overthinking.
- Opus 4.7 (e 4.8) circoscrive il lavoro più stretto a low/medium rispetto a Opus 4.6. Se osservi reasoning superficiale su un prompt complesso a low, alza effort invece di girarci intorno nel prompt. Se la latenza ti costringe a restare a low, aggiungi una riga mirata come 'This task involves multistep reasoning. Think carefully before responding.'
- Effort è la leva principale intelligenza/latenza/costo su Fable 5. Parti da high (il default), usa xhigh per il lavoro più sensibile alla capacità e scendi a medium o low per task di routine — i livelli più bassi su Fable 5 superano comunque i modelli precedenti a xhigh. Imposta un max_tokens grande a high/xhigh perché include thinking più testo di risposta combinati.
- Entrambi i modelli possono spendere pesantemente su subagenti e tool call a xhigh/max. Anthropic raccomanda di partire con max_tokens a 64k e tarare da lì. Lascialo a 4096 e ti ritrovi una risposta troncata con stop_reason='max_tokens' dopo un inizio promettente.
La trappola della cache — quella che raddoppia la bolletta in silenzio
La prompt caching ti dà cache read a circa il 10% del prezzo di input standard. Cambiare effort tra richieste nella stessa conversazione invalida la cache, esattamente come cambiare modello. Su un contesto lungo, è la differenza fra un cache read da $0,03 e una ri-lettura full-price da $0,30 di tutto lo storico — a ogni singolo turno successivo.
- Varia effort TRA i workload, non DENTRO una conversazione cachata. Scegli il livello all'inizio della conversazione; tienilo costante fino al /clear.
- In Claude Code, /effort a metà sessione equivale a cambiare modello — aspettati un grosso cache miss al turno successivo.
- Se devi alzare la profondità per un solo turno, usa 'ultrathink' in Claude Code (un bump di reasoning per un turno solo) invece di /effort xhigh — evita di cambiare la config della sessione.
- Se devi alzare per il resto della sessione, fallo presto. Un cambio al turno 3 è economico; un cambio al turno 30 rilegge 30 turni di contesto a prezzo pieno.
Il corollario: impostare effort="high" esplicitamente su alcune richieste cachate e ometterlo su altre invalida la cache allo stesso modo — perché le due cose sono comportamentalmente equivalenti ma testualmente diverse. Scegli una convenzione (sempre esplicito, o sempre omesso) e tienila.
Claude Code — la superficie CLI
Claude Code espone effort come comando interattivo, come flag di lancio e come variabile d'ambiente (vince la priorità più alta in quest'ordine inverso):
# In-session (interactive slider, or direct)
/effort
/effort xhigh
/effort auto # reset to model default
# At launch
claude --effort low
# Environment (overrides everything else)
CLAUDE_CODE_EFFORT_LEVEL=high claude
Due comandi collegati vale la pena conoscerli perché non sono livelli di effort ma si comportano adiacenti:
ultrathink— un bump di reasoning per un solo turno che non cambia l'effort della sessione. Usalo quando vuoi che il turno successivo pensi più a fondo senza invalidare la cache su tutti i turni seguenti.ultracode— impostaxhigha livello di sessione e concede permesso permanente a Claude Code di lanciare workflow multi-agent (via mid-conversation system message). L'API non ha un valoreultracode— è una comodità CLI che componexhighcon un permesso di orchestrazione.
Regole di persistenza da ricordare: low, medium, high e xhigh persistono tra le sessioni di Claude Code una volta impostati. max si applica solo alla sessione corrente — devi riapplicarlo la volta successiva.
Una passeggiata di tuning — un prompt, tre effort
Per calibrare l'intuito, esegui lo stesso prompt a tre livelli e confronta la forma dell'output:
Prompt di calibrazione tuning (esegui a low, high, xhigh)
Task: Review this pull request for security issues. <pr_diff> [paste a real diff — 300+ lines, multi-file, at least one auth-touching change] </pr_diff> Report: severity-tagged findings + a one-line fix per finding. Do not restate what the diff does.
Aspettati grossomodo:
- low — becca le issue high-severity ovvie (concatenazione SQL, input utente non validato in un header). Perde bug logici sottili. 1-2 tool call se ci sono tool. Output corto. Veloce.
- high — analisi completa. Becca la maggior parte delle vulnerabilità, incluse quelle sottili. Più tool call mirate a leggere file collegati. Finding strutturati. Qui si ferma la maggior parte dei team.
- xhigh — esaustivo. Considera vettori d'attacco nuovi e defence-in-depth. Legge file adiacenti che low/high non toccavano. Molte più tool call. Consumo di token nettamente superiore.
Se le tue eval mostrano che high e xhigh producono gli stessi finding sul tuo codebase, spedisci a high. Il valore di xhigh emerge quando il task beneficia di tool call ripetute ed esplorazione dettagliata — cioè esattamente quando Anthropic lo raccomanda.
Sonnet 5 ha spostato la calibrazione — non portare i livelli a occhi chiusi
Se stavi girando Sonnet 4.6 a high e sei migrato a Sonnet 5, tenere lo stesso livello fa spendere a Sonnet 5 più o meno quello che Sonnet 4.6 spendeva a max — la scala di effort di Sonnet 5 è shiftata. Guida ufficiale di Anthropic: Sonnet 5 medium ≈ Sonnet 4.6 high. È uno swing per-request-cost che vale la pena controllare se hai replayato traffico senza aggiustare effort. Vedi la guida sul campo di Sonnet 5 per la storia completa della migrazione.
Fissalo
Verifica te stesso
0/6Fonti & letture ulteriori
- Anthropic — Effort (build-with-claude/effort) — riferimento autoritativo per i cinque livelli,
output_config.efforte le raccomandazioni per modello - Anthropic — Thinking (build-with-claude/thinking) — come effort interagisce con l'adaptive thinking e quando usare quale controllo
- Release notes Anthropic Platform — voce del 22 luglio 2026 — il rollout di
effortsui Managed Agents e i cambi webhook / session-seeding usciti lo stesso giorno - Prompting Claude Sonnet 5 — calibrare effort e profondità di thinking — lo shift della scala di effort di Sonnet 5 e quando usare xhigh
- Anthropic — Task budgets — budget di token consigliati per loop agentici completi, complemento a effort per run lunghi
- AILmanac — Extended Thinking & Effort — l'inquadramento introduttivo che questa pagina assume
- AILmanac — Claude Sonnet 5: La guida sul campo — la storia di migrazione e ri-calibrazione
- AILmanac — Prompt caching — l'economia della cache che rende così costoso il cambio di effort a metà conversazione