Claude Platform Docs
MessaggiImpegno

Effort

Controlla quanti token Claude utilizza quando risponde con il parametro effort, bilanciando tra completezza della risposta ed efficienza dei token.

L’utilizzo varia in base al prodotto

Messages API
Imposta output_config.effort nella richiesta. Senza un valore, si applica il livello predefinito del modello.
Managed Agents
Imposta effort nell’oggetto modello dell’agente o nell’override del modello di una sessione. Senza un valore, Managed Agents inserisce il valore predefinito del modello.

Il parametro effort ti permette di controllare quanti token Claude spende quando risponde alle richieste. Puoi bilanciare tra completezza della risposta ed efficienza dei token con un singolo modello.

Imposta il livello di effort

Imposta output_config.effort nella richiesta. L’esempio seguente esegue una richiesta con effort medium.

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 usa per impostazione predefinita un effort alto, spendendo tutti i token necessari per ottenere risultati eccellenti; Claude Opus 5.5 e Claude Haiku 5.5 usano per impostazione predefinita 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 a fronte di una certa riduzione delle capacità.

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

  • Risposte testuali e spiegazioni
  • Chiamate agli strumenti e argomenti delle funzioni
  • Ragionamento (quando attivo)

Poiché l’effort si applica a ogni token di output, funziona con o senza ragionamento. Un effort più basso significa anche chiamate agli strumenti meno numerose e più concise.

Livelli di effort

LivelloDescrizioneCaso d’uso tipico
maxCapacità massima in assoluto, senza vincoli sulla spesa di token. Disponibile su Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6 e Claude Haiku 5.5.Attività che richiedono il ragionamento più profondo possibile e l’analisi più approfondita
xhighCapacità estesa per lavori di lungo periodo. Disponibile su Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5 e Claude Haiku 5.5.Attività agentiche e di programmazione di lunga durata (oltre 30 minuti) con budget di token nell’ordine dei milioni
highSpende tutti i token necessari all’attività per ottenere risultati eccellenti. Il valore predefinito su ogni modello che supporta l’effort, eccetto Claude Opus 5.5 e Claude Haiku 5.5.Ragionamento complesso, problemi di programmazione difficili, attività agentiche
mediumApproccio bilanciato con un moderato risparmio di token. Il valore predefinito su Claude Opus 5.5 e Claude Haiku 5.5.Attività agentiche che richiedono un equilibrio tra velocità, costi e prestazioni
lowIl più efficiente. Risparmio significativo di token con una certa riduzione delle capacità.Attività più semplici che richiedono la massima velocità e i costi più bassi, come i subagenti

Non tutti i modelli che supportano max supportano xhigh.

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

Differs by model

Claude Fable 5.2 & Claude Mythos 5.2For demanding reasoning and long-horizon agentic work

Claude Fable 5.2 supporta tutti e cinque i livelli di effort. Il valore predefinito dell’API è high. Il ragionamento adattivo è sempre attivo, quindi l’effort è il tuo controllo principale per la profondità del ragionamento, la latenza e il costo.

Inizia con high. La maggior parte del guadagno in capacità è già presente a high, e al di sopra, i guadagni sono disomogenei e dipendono dall’attività. Passa a xhigh per il tuo lavoro di programmazione e agentico di lunga durata più difficile, dove hai misurato un guadagno. Scendi a medium o low dove le tue valutazioni mostrano che la qualità si mantiene. Riserva max per misurare il limite massimo del modello e per le rare attività in cui tempo e token non contano. A max il modello ottimizza le capacità senza riguardo per il costo dei token. È più lento e costa di più rispetto a xhigh, spesso per un guadagno solo modesto.

Esegui un’analisi comparativa dei livelli di effort sulle tue valutazioni anziché riportare le impostazioni da Claude Fable 5.1. A high e livelli superiori, imposta un valore elevato di max_tokens. È un limite rigido sull’output totale (ragionamento più testo della risposta). L’effort modifica appena la lunghezza delle risposte del modello, quindi usa il prompt per modificare la lunghezza e il tono delle risposte.

Le stesse raccomandazioni si applicano a Claude Mythos 5.2.

Sulle piattaforme supportate, Claude Fable 5.2 e Claude Mythos 5.2 supportano anche la modifica dell’effort a metà conversazione con un output_config per singolo messaggio, che preserva la cache dei prompt.

Effort con l’uso degli strumenti

Quando si usano gli 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 ragionamento

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 ragiona più prontamente 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 del tutto 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 ragionamento esteso che supporta l’effort, questo funziona insieme a budget_tokens: imposta il livello di effort per la tua attività, poi imposta il budget di token per il ragionamento in base alla profondità di ragionamento di cui l’attività ha bisogno.

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

Modificare l’effort a metà conversazione

Puoi eseguire i turni successivi di una conversazione a un livello di effort diverso in due modi. Una modifica dell’effort per messaggio mantiene la cache dei prompt. Un nuovo valore di primo livello nella richiesta successiva può invalidare in tutto o in parte la cache dei prompt.

Effort per messaggio

L’effort per messaggio imposta un nuovo livello con un messaggio system in messages.

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 una richiesta e l’altra può invalidare 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 usa 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 conversazione.
  5. Mantieni costante l’effort di primo livello nelle conversazioni con cache: Modificare il valore di effort di primo livello tra una richiesta e l’altra può invalidare in tutto o in parte la cache dei prompt, quindi varialo tra carichi di lavoro diversi piuttosto che all’interno di una conversazione che fa affidamento sugli hit della cache. Sui modelli che la supportano, usa invece una modifica dell’effort per messaggio, che preserva la cache. Consulta Ragionamento e cache dei prompt.

Passaggi successivi

Fornisci a Claude un budget di token indicativo per l’intero ciclo agentico, per aiutare il modello ad autoregolarsi nelle attività agentiche lunghe.

Comprendi il ragionamento adattivo, in cui Claude determina quando e quanto ragionare, e orientalo con l’effort e il prompting.

Comprendi come funziona il ragionamento, quando Claude ragiona per impostazione predefinita e come il ragionamento interagisce con l’effort.

Disponibilità

Effort
API
  • Messages API
  • Managed Agents
Modelli
  • Claude Fable 5.2, Fable 5.1, Fable 5
  • Claude Mythos 5.2, Mythos 5.1, Mythos 5, Mythos Preview
  • Claude Opus 5.5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5
  • Claude Sonnet 5.5, Sonnet 5, Sonnet 4.6
  • Claude Haiku 5.5

Endpoint applicabili

  • /v1/messages con effort
Conservazione zero dei datiIdoneo

Esclude Modelli coperti

HIPAAIdoneo

Questa pagina ti è stata utile?