Effort per messaggio

Una modifica dell’effort per messaggio imposta un nuovo livello di effort per i turni successivi di una conversazione senza modificare il valore di primo livello della richiesta, quindi il prefisso in cache corrisponde ancora.

Modificare il livello di effort

Per modificare il livello a metà di una conversazione:

1. Aggiungi un messaggio role: "system" a messages, con content vuoto e il nuovo livello di effort in output_config.effort.
2. Invia il beta header mid-conversation-output-config-2026-07-01.
3. Lascia invariato il valore di primo livello.

L’esempio seguente mantiene il valore di primo livello a high e scende a low per un 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 dell'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)

La posizione del messaggio determina quando inizia il nuovo livello:

• Subito dopo un turno user con un nuovo input: la risposta di Claude a quel turno usa il nuovo livello.
• In qualsiasi altra posizione, ad esempio tra un turno assistant e il turno user successivo come nell’esempio precedente: il nuovo livello inizia dal successivo turno user con un nuovo input.

Un turno user che contiene solo blocchi tool_result non conta come nuovo input.

Il nuovo livello rimane in vigore finché un messaggio successivo non lo modifica.

Inserisci il messaggio dopo tutto ciò che hai già inviato e mantienilo nella stessa posizione nelle richieste successive. Non inserirlo prima di turni che hai già inviato e non spostarlo né rimuoverlo in seguito. Sui modelli con ragionamento preservato, ognuna di queste modifiche invalida i blocchi di ragionamento nei turni assistant successivi al messaggio. Cosa fa l’API con un blocco non valido spiega cosa succede dopo.

Se si trova accanto a un messaggio system che ha contenuto, entrambi i messaggi devono seguire le regole di posizionamento per i messaggi di sistema a metà conversazione.

Con l’API InvokeModel di Amazon Bedrock, invia il valore beta nell’array anthropic_beta del corpo della richiesta invece che nell’header. Per i modelli che supportano lì l’effort per messaggio, consulta Messaggi di sistema a metà conversazione su Bedrock.

Errori

• Senza il beta header, 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 beta header, i modelli senza effort per messaggio, come 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 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"}, non puoi modificare il livello di effort a metà conversazione. In questi casi, un output_config.effort per messaggio con un nuovo livello restituisce un errore 400. Per variare l’effort a ogni turno, usa il ragionamento adattivo.

Effort per messaggio o di primo livello

Preferisci l’effort per messaggio rispetto alla modifica del valore di primo livello tra una richiesta e l’altra. Una modifica per messaggio lascia invariato tutto ciò che la precede, quindi il prefisso in cache corrisponde ancora. Una modifica di primo livello fa ripartire la cache. Su Claude Fable 5.1, una modifica di primo livello guida anche il modello in modo meno affidabile. Le risposte precedenti del modello sono state scritte al livello precedente e il modello tende a rimanere coerente con esse.

Disponibilità