Controlli del prefisso sui blocchi di ragionamento

Ogni richiesta che rinvia blocchi di ragionamento a un modello con ragionamento preservato è sottoposta a un “prefix check” (controllo del prefisso). Un controllo del prefisso non viene superato se system, tools o un messaggio precedente sono cambiati dopo che Claude ha prodotto un blocco. Non viene superato nemmeno se un blocco di ragionamento tra altri è stato omesso o spostato.

Non superare il controllo del prefisso può causare o meno un errore 400, a seconda del modello, quindi gestisci entrambi i casi.

Chi è interessato dal controllo del prefisso

Non hai nulla da modificare se una di queste condizioni è vera:

• Claude Code, claude.ai o Claude Managed Agents gestisce la cronologia della tua conversazione.
• Il Claude Agent SDK gestisce la cronologia e il prompt di sistema che fornisci all’SDK rimane invariato.
• Il tuo codice segue le tre abitudini di un’integrazione append-only e nulla riscrive le sue richieste lungo il percorso.
• Non chiami alcun modello con ragionamento preservato.

Se le tue richieste passano attraverso una libreria, un proxy o un gateway, confronta ciò che invia con ciò che hai inviato tu. Se ne gestisci uno, consulta Librerie, proxy e gateway per sapere cosa lasciar passare.

Cosa deve rimanere invariato e perché

Rendi la tua integrazione “append-only” (solo in aggiunta). Tre abitudini ti permettono di farlo:

1. Rinvia ogni turno dell’assistente esattamente come l’API lo ha restituito, inclusi i blocchi di ragionamento il cui testo è vuoto.
2. Costruisci system e tools una sola volta per ogni conversazione e invia quella copia ogni volta.
3. Inserisci ogni aggiornamento in un nuovo messaggio alla fine e lascialo lì.

Il ragionamento di ogni blocco di ragionamento riguarda esattamente ciò che lo precedeva: system, tools e ogni messaggio precedente. Quel contenuto è il prefisso del blocco ed è ciò che il controllo del prefisso confronta.

Il controllo del prefisso è simile alla cache dei prompt, tranne per il fatto che una modifica rende non valido il ragionamento che la segue invece di causare soltanto un mancato riscontro nella cache.

Prendi un’app che inserisce la data odierna nel suo prompt di sistema. A mezzanotte la data cambia, e con essa il prefisso del ragionamento già presente nella conversazione. Quel ragionamento diventa non valido e la richiesta successiva può fallire. Un’app append-only mantiene il prompt di sistema com’era e indica la nuova data in un messaggio alla fine.

Una modifica rende non valido solo il ragionamento che già la segue. Il ragionamento precedente e il ragionamento che Claude produce successivamente restano validi.

Se il tuo codice modifica il prompt di sistema, gli strumenti o la cronologia

Altre cause, come saltare i blocchi di ragionamento il cui testo è vuoto o ricostruire una conversazione salvata, hanno soluzioni proprie: consulta Modifica strumenti o istruzioni senza fallire il controllo del prefisso. Per trovare la tua, fai controllare il tuo codice a un agente.

Cosa fa ciascun modello quando il controllo del prefisso non viene superato

Sulla Claude API e su alcune piattaforme cloud, il risultato del mancato superamento del controllo del prefisso con prefix_mismatch_behavior non impostato dipende dal modello:

Dove la tabella indica “Possibile errore 400”, ci sono due casi: una richiesta che non supera il controllo del prefisso potrebbe ricevere un errore 400 oppure nessun errore. Quando non viene restituito alcun errore, i blocchi che non superano il controllo del prefisso raggiungono il modello. Claude li legge come qualsiasi altro input, ti vengono addebitati e Claude lavora a partire da un ragionamento su contenuti che nel frattempo sono cambiati.

Su quei modelli puoi verificare quale caso riceve una richiesta, ma gestisci entrambi i casi.

Gli elementi di Message Batches che lasciano prefix_mismatch_behavior non impostato non ricevono alcun errore, e l’API può scartare i blocchi che non superano il controllo del prefisso.

Gestisci entrambi i casi

Per ottenere un unico risultato su ogni richiesta, rendi la tua integrazione append-only oppure imposta prefix_mismatch_behavior. Altrimenti, il tuo codice deve gestire entrambi i comportamenti.

• Append-only: con le tre abitudini, il tuo codice non fa sì che una richiesta non superi il controllo del prefisso.
• L’impostazione: con "error" su ogni richiesta, ogni mancato superamento del controllo del prefisso è un errore 400, e lo intercetti nel codice.
• Entrambi i comportamenti: se lasci l’impostazione non impostata, intercetta l’errore 400 e monitora il ragionamento che non ha superato il controllo del prefisso e ha raggiunto Claude.

Dopo un errore 400, invia "drop_block" nelle richieste successive di quella conversazione per ripristinarla. Ha un costo: consulta Quanto costa scartare il ragionamento. Non inviarlo su tutte le tue conversazioni per nascondere gli errori.

Dettagli tecnici

Come funziona il controllo del prefisso

I modelli con ragionamento preservato registrano un’impronta del prefisso di ogni blocco di ragionamento nella sua signature. Il riferimento dell’API chiama il controllo del prefisso “controllo della conversazione”, e l’errore 400 indica che un blocco che non supera il controllo del prefisso is bound to a different conversation.

Quali modelli eseguono il controllo del prefisso

Il controllo del prefisso viene eseguito sulla Claude API e su alcune piattaforme cloud. Controlla i blocchi di ragionamento prodotti da un modello con ragionamento preservato, nelle richieste a uno di quei modelli. Sulla Claude API, gli altri modelli, come Claude Opus 5, non lo eseguono, e il controllo del prefisso non copre i loro blocchi.

Cosa conta come modifica

• Ogni blocco viene controllato rispetto alla propria registrazione. L’API confronta ciò che precede un blocco in questa richiesta con ciò che la sua firma ha registrato quando Claude lo ha prodotto. La tua ultima richiesta non ha alcun ruolo. Il controllo del prefisso considera solo il contenuto, non sessioni, ID o utenti. Lo stesso contenuto in una nuova richiesta o in un fork lo supera.
• Il controllo del prefisso confronta ciò che hai inviato, non ciò che Claude ha letto. La Compattazione a una soglia di token e il “context editing” (modifica del contesto) cambiano solo ciò che Claude legge, quindi non contano mai. Dopo un blocco di compattazione a soglia, l’API confronta solo i messaggi a partire da quel blocco, più system e tools. La compattazione su richiesta ha condizioni proprie: consulta Condizioni affinché il ragionamento mantenuto rimanga valido. Per un file inviato tramite URL e, sulla Claude API, per un elenco di strumenti MCP, l’API confronta invece ciò che ha recuperato.
• Il ragionamento che invii deve essere una sequenza ininterrotta. I blocchi di ragionamento non vengono confrontati come contenuto. Ma ciascuno di quelli che invii, a parte il primo, deve avere lo stesso blocco di ragionamento precedente che aveva quando Claude lo ha prodotto. Quindi puoi omettere il più vecchio, il più recente o tutti, ma non uno intermedio.

Una modifica può essere piccola quanto una parola della descrizione di uno strumento. Modificare, inserire, spostare o eliminare un messaggio precedente conta, qualunque sia il suo ruolo. Lo stesso vale per la modifica del testo che precede un blocco di ragionamento nel suo stesso messaggio.

Cosa non conta

Imposta prefix_mismatch_behavior

L’header beta thinking-binding-controls-2026-08-01 aggiunge l’impostazione thinking.block_binding.prefix_mismatch_behavior e l’array input_transformations della risposta.

I blocchi che non superano il controllo del prefisso restano non validi in ogni richiesta successiva che li invia, finché la modifica è presente. L’impostazione agisce sulla singola richiesta che la contiene. Con il ragionamento disattivato ("disabled" o "between_tools"), inviarla produce un errore 400 su ogni modello.

La richiesta seguente imposta prefix_mismatch_behavior su "drop_block". Al primo turno non c’è alcun ragionamento da rinviare, quindi input_transformations viene restituito vuoto:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "block_binding": {"prefix_mismatch_behavior": "drop_block"},
    },
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
    betas=["thinking-binding-controls-2026-08-01"],
)

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

print(f"Input transformations: {len(response.input_transformations or [])}")

Monitora il traffico di produzione

Con prefix_mismatch_behavior non impostato, una richiesta che non supera il controllo del prefisso potrebbe non ricevere alcun errore su alcuni modelli. I blocchi di ragionamento che non lo hanno superato raggiungono quindi il modello. Per trovare quei blocchi nel traffico di produzione, invia l’header beta thinking-binding-controls-2026-08-01, lascia l’impostazione non impostata e registra l’array input_transformations di ogni risposta. L’header aggiunge quell’array e non modifica ciò che il modello riceve.

Ciascuno di quei blocchi ottiene una propria voce thinking_mismatch_allowed in quell’array. Una voce ha questo aspetto:

{
  "input_transformations": [
    {
      "type": "thinking_mismatch_allowed",
      "path": "messages.1.content.0",
      "reason": "prefix_binding_mismatch"
    }
  ]
}

Per trovare la modifica, consulta Trova cosa ha modificato il tuo codice.

Verifica quale caso ricevi

Su alcuni modelli, una richiesta che non supera il controllo del prefisso potrebbe ricevere l’errore 400 oppure nessun errore. Questo test mostra quale dei due riceve una richiesta:

1. Prendi una conversazione che contiene un blocco di ragionamento di uno di quei modelli. Modifica o aggiungi il prompt di sistema (system). Il blocco quindi non supera il controllo del prefisso, perché il prompt di sistema è cambiato dopo che Claude ha prodotto il blocco.
2. Inviala allo stesso modello con l’header beta thinking-binding-controls-2026-08-01 e lascia prefix_mismatch_behavior non impostato.

La risposta è una delle seguenti:

• Un errore 400 che riporta bound to a different conversation: la richiesta ha ricevuto l’errore 400.
• Una risposta 200 il cui array input_transformations contiene voci thinking_mismatch_allowed: la richiesta non ha ricevuto alcun errore. Ogni voce indica un blocco di ragionamento che non ha superato il controllo del prefisso e ha raggiunto Claude.
• Una risposta 200 il cui array input_transformations è vuoto: nessun blocco non ha superato il controllo del prefisso, quindi il test non mostra nulla. Verifica che la conversazione contenga un blocco di ragionamento di quel modello.

Il risultato descrive quella singola richiesta e non garantisce nulla sulle successive, quindi scrivi il tuo codice in modo da gestire entrambi i casi.

Passaggi successivi