Effort

Il parametro "effort" (impegno) ti consente di controllare quanti token Claude spende quando risponde alle richieste. Puoi bilanciare tra completezza della risposta ed efficienza dei token con un singolo modello. Il parametro effort di primo livello è disponibile su tutti i modelli supportati senza necessità di header beta. L'effort per messaggio è in beta.

Imposta il livello di effort

Imposta output_config.effort nella richiesta. L'esempio seguente esegue una richiesta con effort medium e stampa il testo della risposta.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Come funziona l'effort

La maggior parte dei modelli Claude utilizza per impostazione predefinita un effort alto, spendendo tutti i token necessari per ottenere risultati eccellenti; Claude Opus 5.5 e Claude Haiku 5.5 utilizzano per impostazione predefinita il livello medium. Puoi aumentare il livello di effort a max per ottenere la massima capacità in assoluto, oppure abbassarlo per essere più parsimonioso nell'uso dei token, ottimizzando velocità e costi e accettando una certa riduzione delle capacità.

Il parametro effort influisce su tutti i token della risposta, inclusi:

• Risposte testuali e spiegazioni
• Chiamate agli strumenti e argomenti delle funzioni
• Il "thinking" (ragionamento), quando attivo

Poiché l'effort si applica a ogni token di output, funziona indipendentemente dal fatto che il ragionamento sia abilitato o meno. Un effort più basso comporta anche chiamate agli strumenti meno numerose e più concise.

Livelli di effort

Non tutti i modelli che supportano max supportano xhigh.

Le raccomandazioni per modello che seguono prevalgono su questa tabella laddove differiscono.

Livelli di effort consigliati per Claude Fable 5.1

Claude Fable 5.1 supporta tutti e cinque i livelli di effort. Inizia con high, il valore predefinito. Sali a xhigh o max per i lavori agentici e di coding più sensibili alle capacità, e scendi a medium o low per lavori di routine o sensibili alla latenza una volta che le tue valutazioni mostrano che la qualità si mantiene. A high e oltre, imposta un max_tokens ampio. È un limite rigido sull'output totale (thinking più testo della risposta). Le stesse raccomandazioni si applicano a Claude Mythos 5.1. Consulta Prompting per Claude Fable 5.1.

Claude Fable 5.1 supporta anche la modifica dell'effort a metà conversazione con un output_config per messaggio, che preserva la cache dei prompt.

Livelli di effort consigliati per Claude Fable 5

L'effort è il controllo principale per bilanciare intelligenza, latenza e costo su Claude Fable 5. Inizia con high, il valore predefinito, per la maggior parte delle attività, usa xhigh per i carichi di lavoro più sensibili alle capacità e scendi a medium o low per i lavori di routine. Le impostazioni di effort più basse su Claude Fable 5 offrono comunque buone prestazioni e spesso superano le prestazioni di xhigh sui modelli precedenti. A high e xhigh, imposta un max_tokens ampio. È un limite rigido sull'output totale (thinking più testo della risposta). Consulta Controllo dei costi.

Riduci l'effort se un'attività viene completata ma richiede più tempo del necessario, o se desideri uno stile di lavoro più rapido e interattivo. Le stesse raccomandazioni si applicano a Claude Mythos 5. Per indicazioni più complete, consulta Prompting per Claude Fable 5.

Livelli di effort consigliati per Claude Opus 5.5

Claude Opus 5.5 supporta tutti e cinque i livelli di effort, e medium è il valore predefinito (Claude Opus 5 e i modelli Opus precedenti usano high come predefinito, quindi una richiesta che omette effort viene eseguita a un livello inferiore rispetto a Claude Opus 5). Il ragionamento adattivo è sempre attivo e non può essere disattivato, quindi l'effort è il controllo principale per stabilire quanto il modello ragiona e quanto costa una richiesta. Esegui una scansione dei livelli di effort sulle tue valutazioni invece di riportare le impostazioni da un modello precedente, e imposta un valore elevato di max_tokens ai livelli più alti: si tratta di un limite rigido sull'output totale (ragionamento più testo della risposta). Le richieste che impostano thinking: {"type": "disabled"} restituiscono un errore 400 a qualsiasi livello di effort. Claude Opus 5.5 supporta anche la modifica dell'effort a metà conversazione con un output_config per messaggio, che preserva la cache dei prompt. Consulta Prompting di Claude Opus 5.5.

Livelli di effort consigliati per Claude Opus 5

Claude Opus 5 supporta tutti e cinque i livelli di effort. Inizia con high, il valore predefinito, e regola in base alle tue valutazioni: passa a xhigh per il lavoro di coding e agentico impegnativo, o a max quando un'attività giustifica una spesa di token senza vincoli, e usa liberamente low e medium come controllo principale per il costo dei token e il tempo di risposta ovunque le tue valutazioni mostrino che la qualità si mantiene. Se hai riportato le impostazioni di effort da un modello precedente, esegui una nuova scansione dei livelli di effort sulle tue valutazioni invece di riutilizzarle.

L'effort controlla il volume del ragionamento, non la lunghezza visibile della risposta: su Claude Opus 5, modificare l'effort non accorcia in modo affidabile le risposte, quindi specifica la lunghezza nel prompt.

Il valore predefinito dell'API è high. Imposta effort esplicitamente per usare un livello diverso. Il valore che passi prevale su quello predefinito.

Su Claude Opus 5, il ragionamento non può essere disabilitato con effort xhigh o max: le richieste che impostano thinking: {"type": "disabled"} a quei livelli restituiscono un errore 400. Consulta Effort con il thinking.

Quando esegui Claude Opus 5 con effort xhigh o max, imposta un max_tokens elevato in modo che il modello abbia spazio per ragionare e agire attraverso subagenti e chiamate agli strumenti. Iniziare da 64k token e regolare da lì è un valore predefinito ragionevole.

Claude Opus 5 supporta anche la modifica dell'effort a metà conversazione con un output_config per messaggio, che preserva la cache dei prompt. L'effort per messaggio non è disponibile per Claude Opus 5 su Amazon Bedrock.

Livelli di effort consigliati per Claude Opus 4.8

Le indicazioni per Claude Opus 4.7 si applicano anche a Claude Opus 4.8. Inizia con xhigh per i casi d'uso di coding e agentici, usa high per la maggior parte degli altri carichi di lavoro sensibili all'intelligenza e scendi a medium o low solo quando hai misurato che il livello inferiore mantiene la qualità sulle tue valutazioni.

Il valore predefinito dell'API è high. Imposta effort esplicitamente per usare un livello diverso. Il valore che passi sovrascrive quello predefinito.

Quando esegui Claude Opus 4.8 con effort xhigh o max, imposta un max_tokens ampio in modo che il modello abbia spazio per pensare e agire attraverso subagenti e chiamate agli strumenti. Partire da 64k token e regolare da lì è un valore predefinito ragionevole.

Livelli di effort consigliati per Claude Opus 4.7

Inizia con xhigh per i casi d'uso di coding e agentici, e usa high come minimo per la maggior parte dei carichi di lavoro sensibili all'intelligenza. Scendi a medium per i carichi di lavoro sensibili ai costi, o sali a max solo quando le tue valutazioni mostrano un margine di miglioramento misurabile rispetto a xhigh.

Il valore predefinito dell'API è high. Per usare xhigh, imposta effort esplicitamente. Il valore che passi prevale su quello predefinito.

Claude Opus 4.7 rispetta inoltre i livelli di effort in modo più rigoroso rispetto a Claude Opus 4.6, specialmente a low e medium. A livelli di effort più bassi, il modello limita il proprio lavoro a ciò che è stato richiesto invece di fare più del necessario. Se osservi un ragionamento superficiale su problemi complessi con Claude Opus 4.7, aumenta l'effort invece di aggirare il problema tramite il prompt. Se devi mantenere l'effort basso per motivi di latenza, aggiungi indicazioni mirate come "Questa attività comporta un ragionamento in più passaggi. Pensa attentamente prima di rispondere."

Quando esegui Claude Opus 4.7 con effort xhigh o max, imposta un max_tokens elevato in modo che il modello abbia spazio per ragionare e agire attraverso subagenti e chiamate agli strumenti. Iniziare da 64k token e regolare da lì è un valore predefinito ragionevole.

Livelli di effort consigliati per Claude Sonnet 5.5

Claude Sonnet 5.5 supporta tutti e cinque i livelli di effort, e high è il valore predefinito sulla Claude API. I suoi livelli sono ricalibrati, quindi un livello non produce la stessa quantità di ragionamento dello stesso livello su Claude Sonnet 5. Esegui una nuova scansione dei livelli di effort sulle tue valutazioni invece di riportare l'impostazione che usavi su Claude Sonnet 5. Inizia con high a meno che il tuo carico di lavoro non sia agentico o sensibile alla latenza. Per la programmazione agentica e l'uso degli strumenti in più passaggi, inizia con medium per attività ben specificate e passa a high per quelle più difficili o più lunghe. Per la chat e altri lavori sensibili alla latenza, inizia con medium o low. Usa xhigh o max solo dove le tue valutazioni mostrano un guadagno di qualità. Imposta max_tokens lasciando spazio per il ragionamento e la risposta. Il ragionamento conta ai fini di max_tokens anche quando il contenuto del ragionamento non viene restituito. Per la programmazione agentica, imposta max_tokens a 128.000, il massimo del modello, e usa lo streaming per la risposta.

Per disattivare il ragionamento iniziale, invia thinking: {"type": "between_tools"} invece di "disabled". È l'impostazione di ragionamento più bassa su Claude Sonnet 5.5 e funziona con effort low, medium e high. A xhigh o max, una richiesta con questa impostazione restituisce un errore 400, quindi usa il ragionamento adattivo a quei livelli: ometti il campo thinking o invia thinking: {"type": "adaptive"}. Consulta Esecuzione senza ragionamento iniziale.

Claude Sonnet 5.5 supporta anche la modifica dell'effort a metà conversazione con un output_config per messaggio, che preserva la cache dei prompt. Con between_tools, l'effort non può cambiare a metà conversazione: un output_config.effort per messaggio che differisce dal livello in vigore restituisce un errore 400. Per variare l'effort a ogni turno, usa il ragionamento adattivo. Consulta Scrivere prompt per Claude Sonnet 5.5.

Livelli di effort consigliati per Claude Sonnet 5

Claude Sonnet 5 usa per impostazione predefinita l'effort high sulla Claude API e su Claude Code.

• Effort high (predefinito): Adatto per ragionamento complesso, coding e attività agentiche in cui la qualità conta più della velocità o del costo.
• Effort xhigh: Per le attività di coding e agentiche più difficili. Consulta Prompting per Claude Sonnet 5.
• Effort medium: Riduzione rispetto al valore predefinito per risparmiare sui costi. Paragonabile a Claude Sonnet 4.6 con effort high.
• Effort low: Per carichi di lavoro ad alto volume o sensibili alla latenza. Adatto per chat e casi d'uso non di coding in cui si privilegiano tempi di risposta più rapidi.
• Effort max: Per attività che richiedono la capacità assolutamente più elevata senza vincoli sulla spesa di token.

Livelli di effort consigliati per Claude Sonnet 4.6

Sonnet 4.6 utilizza per impostazione predefinita l'effort high. Imposta esplicitamente l'effort quando usi Sonnet 4.6 per evitare latenze impreviste:

• Effort medium (valore predefinito consigliato): Il miglior equilibrio tra velocità, costi e prestazioni per la maggior parte delle applicazioni. Adatto per il coding agentico, i flussi di lavoro con uso intensivo di strumenti e la generazione di codice.
• Effort low: Per carichi di lavoro ad alto volume o sensibili alla latenza. Adatto per chat e casi d'uso non di coding in cui si privilegiano tempi di risposta più rapidi.
• Effort high: Per ragionamento complesso e attività in cui la qualità conta più della velocità o dei costi.
• Effort max: Per attività che richiedono la massima capacità in assoluto senza vincoli sulla spesa di token.

Livelli di effort consigliati per Claude Haiku 5.5

Claude Haiku 5.5 supporta tutti e cinque i livelli di effort, e medium è il valore predefinito sulla Claude API e in Claude Code. L'effort è il controllo principale per quanto il modello ragiona e, di conseguenza, per qualità, latenza e costi. Inizia con medium per la maggior parte del lavoro, incluso il coding agentico. Usa low, il livello più economico e veloce, per la chat, le attività brevi con strumenti e le richieste semplici ad alto volume. Nei prompt lunghi per agenti, a low è più probabile che il modello salti una ricerca, si fermi prima del tempo o salti una verifica. Usa high per il lavoro di conoscenza, le attività agentiche più lunghe e il rispetto rigoroso delle istruzioni. Usa xhigh o max solo dove le tue valutazioni mostrano un guadagno di qualità, e confrontali con Claude Sonnet 5.5 in termini di prestazioni, costi e velocità. Il ragionamento è attivo per impostazione predefinita e conta ai fini di max_tokens, quindi lascia spazio per esso. Consulta Prompting per Claude Haiku 5.5.

Per ottenere meno ragionamento, abbassa il livello di effort. Puoi anche inviare thinking: {"type": "disabled"} con effort high o inferiore. A xhigh o max, restituisce un errore 400, quindi usa il ragionamento adattivo a quei livelli: ometti il campo thinking o invia thinking: {"type": "adaptive"}.

Sulla Claude API e su Google Cloud, Claude Haiku 5.5 supporta anche la modifica dell'effort a metà conversazione con un output_config per messaggio, che preserva la cache dei prompt. Con thinking: {"type": "disabled"}, l'effort non può cambiare a metà conversazione: un output_config.effort per messaggio che differisce dal livello in vigore restituisce un errore 400. Per variare l'effort a ogni turno, usa il ragionamento adattivo.

Effort con l'uso degli strumenti

Quando si usano strumenti, il parametro effort influisce sia sulle spiegazioni attorno alle chiamate agli strumenti sia sulle chiamate stesse. I livelli di effort più bassi tendono a:

• Combinare più operazioni in meno chiamate agli strumenti
• Effettuare meno chiamate agli strumenti
• Procedere direttamente all'azione senza preamboli
• Usare messaggi di conferma concisi dopo il completamento

I livelli di effort più alti possono:

• Effettuare più chiamate agli strumenti
• Spiegare il piano prima di agire
• Fornire riepiloghi dettagliati delle modifiche
• Includere commenti al codice più completi

Effort con il thinking

Il parametro thinking controlla se Claude riflette in blocchi di ragionamento prima di rispondere; il parametro effort controlla quanto lavoro Claude dedica all'intera risposta, il che in modalità adattiva include quanto spesso e quanto profondamente riflette. Non passare adaptive come valore di effort: adaptive è una modalità di ragionamento, non un livello di effort.

A livelli di effort più alti, Claude pensa più facilmente e più a lungo. In un ciclo di uso degli strumenti, le richieste successive che elaborano solo i risultati degli strumenti possono comunque saltare il ragionamento a qualsiasi livello. A livelli più bassi, Claude può saltare completamente il ragionamento per i problemi più semplici. Consulta Ragionamento ed effort per indicazioni complete su come i due controlli funzionano insieme.

Su Claude Opus 4.5, l'unico modello con solo "extended thinking" (ragionamento esteso) che supporta l'effort, questo funziona insieme a budget_tokens: imposta il livello di effort per la tua attività, quindi imposta il budget di token per il thinking in base alla profondità di ragionamento richiesta dall'attività.

Per la disponibilità del thinking per modello, consulta la tabella di configurazione per modello. L'effort funziona con o senza thinking. Consulta Come funziona l'effort.

Cambiare l'effort a metà conversazione

Puoi eseguire i turni successivi di una conversazione a un livello di effort diverso in due modi. Su Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 e Claude Haiku 5.5, usa una modifica dell'effort per messaggio, che mantiene la cache dei prompt. Sugli altri modelli, imposta un nuovo valore di primo livello nella richiesta successiva, il che fa ripartire la cache da zero.

Effort per messaggio (beta)

L'effort per messaggio è in beta. Sulla Claude API e su Google Cloud, è disponibile su Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 e Claude Haiku 5.5. Su Amazon Bedrock, è disponibile su Claude Fable 5.1, Claude Mythos 5.1 e Claude Opus 5.5. Richiede l'header beta mid-conversation-output-config-2026-07-01. Con l'API InvokeModel di Amazon Bedrock, è disponibile su Claude Fable 5.1 e Claude Opus 5.5, e in questo caso invii quel valore nell'array anthropic_beta del corpo della richiesta.

Senza il valore beta, un output_config per messaggio restituisce un errore 400: messages.N.output_config: Extra inputs are not permitted, dove N è l'indice del messaggio system in messages. Con il valore beta, i modelli senza effort per messaggio, incluso Claude Fable 5, restituiscono un errore 400: output_config.effort requires a model that supports per-turn effort; this model does not. Su Amazon Bedrock, quei modelli e Claude Opus 5 restituiscono invece l'errore Extra inputs are not permitted. Su Claude Sonnet 5.5 con thinking: {"type": "between_tools"} e su Claude Haiku 5.5 con thinking: {"type": "disabled"}, l'effort non può cambiare a metà conversazione: un output_config.effort per messaggio che differisce dal livello in vigore restituisce un errore 400. Per variare l'effort a ogni turno, usa il ragionamento adattivo.

Aggiungi un messaggio role: "system" con content vuoto e il nuovo livello in output_config.effort. Il nuovo livello ha effetto a partire dal turno user successivo e rimane valido finché un messaggio successivo non lo modifica. Tutto ciò che precede quel messaggio rimane invariato, quindi il prefisso in cache continua a corrispondere.

L'esempio seguente inizia con high, poi scende a low per una domanda di follow-up di routine:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=4096,
    output_config={"effort": "high"},
    messages=[
        {
            "role": "user",
            "content": "Plan a migration from SQLite to PostgreSQL in three short steps.",
        },
        {
            "role": "assistant",
            "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.",
        },
        # Messaggio di sistema solo per l'effort: il nuovo livello si applica dal prossimo turno utente.
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "Summarize the plan in one sentence."},
    ],
    betas=["mid-conversation-output-config-2026-07-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Un messaggio di sistema con solo l'effort non contiene testo, quindi le regole di posizionamento per i messaggi di sistema a metà conversazione non si applicano. Può comparire in qualsiasi punto di messages, anche come prima voce o tra un turno assistant e il turno user successivo. I valori sono i nomi dei livelli (low, medium, high, xhigh e max).

Su Claude Fable 5.1, preferisci questa forma alla modifica del valore di primo livello tra una richiesta e l'altra. Una modifica di primo livello fa ripartire la cache e inoltre orienta il modello in modo meno affidabile: le sue risposte precedenti sono state scritte al livello precedente e il modello tende a rimanere coerente con esse.

Effort di primo livello nella richiesta successiva

L'output_config.effort di primo livello si applica all'intera richiesta. Per eseguire una parte successiva di una conversazione a un livello diverso, imposta il nuovo valore nella richiesta successiva. Poiché l'effort di primo livello modella il prompt renderizzato, modificarlo tra le richieste non preserva i prefissi in cache dei turni precedenti. Se fai affidamento sulla cache dei prompt in una sessione lunga e il tuo modello non supporta l'effort per messaggio, scegli un livello di effort all'inizio e mantienilo costante.

Best practice

1. Imposta l'effort esplicitamente: L'API utilizza per impostazione predefinita high (medium su Claude Opus 5.5 e Claude Haiku 5.5), ma il punto di partenza giusto dipende dal tuo modello e dal tuo carico di lavoro.
2. Usa low per attività sensibili alla velocità o semplici: Quando la latenza è importante o le attività sono semplici, un effort basso può ridurre significativamente i tempi di risposta e i costi.
3. Testa il tuo caso d'uso: L'impatto dei livelli di effort varia in base al tipo di attività. Valuta le prestazioni sui tuoi casi d'uso specifici prima del deployment.
4. Considera un effort dinamico: Regola l'effort in base alla complessità dell'attività. Le query semplici possono giustificare un effort basso, mentre la programmazione agentica e il ragionamento complesso traggono vantaggio da un effort alto. Consulta il punto successivo prima di variarlo all'interno di una stessa conversazione.
5. Mantieni costante l'effort di primo livello nelle conversazioni in cache: Modificare il valore dell'effort di primo livello tra una richiesta e l'altra invalida la cache dei prompt, quindi varialo tra carichi di lavoro diversi anziché all'interno di una conversazione che si basa sugli hit della cache. Sui modelli che lo supportano, usa invece una modifica dell'effort per messaggio, che preserva la cache. Consulta Ragionamento e cache dei prompt.

Passaggi successivi

Compatibility