Modifica strumenti o istruzioni senza fallire il controllo del prefisso

Per aggiornare strumenti, istruzioni o altro contesto, lascia tutto ciò che hai inviato così com’era e aggiungi l’aggiornamento alla fine, dove rimane. Sui modelli con “preserved thinking” (ragionamento preservato), modificare ciò che hai inviato può rendere non valido il ragionamento successivo, e la richiesta può fallire.

I modelli con “preserved thinking” (ragionamento preservato) sono Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5.

Rinvia i turni dell’assistente esattamente come sono

Rinvia l’intero array content di ogni risposta, in ordine, inclusi i blocchi di ragionamento il cui testo è vuoto. Un blocco con testo vuoto è completo, perché la sua signature contiene il ragionamento, cifrato. Un turno che contiene un blocco fallback ha una regola propria.

Serializzatori, filtri e parser di stream possono compromettere questo aspetto.

Modifica le istruzioni

Mantieni system uguale in ogni richiesta. Inserisci le tue istruzioni in un messaggio role: "system" alla fine, e inviane uno solo quando qualcosa è cambiato. Claude lo tratta come un’istruzione da parte tua, l’operatore. Lascialo per il resto della conversazione, perché eliminarlo o riformularlo in seguito rende non valido il ragionamento successivo. Le parole del tuo utente hanno una regola propria.

Un promemoria che deve accompagnare ogni turno è diverso: inviane uno che si disattiva da solo.

Il messaggio di sistema va dopo il messaggio utente più recente, anche uno con risultati degli strumenti. Un messaggio di sistema con blocchi di testo o di strumenti riceve un errore 400 subito dopo il turno di Claude o subito prima di un messaggio utente. Quindi, quando il turno di Claude è l’ultimo, attendi che il messaggio utente successivo sia al suo posto.

Un messaggio di sistema non garantisce che Claude segua un’istruzione, quindi applica limiti come la modalità di sola lettura nel codice che esegue i tuoi strumenti. Alcuni modelli non accettano messaggi di sistema.

Testo che altre persone possono modificare

Chiediti se il tuo utente si aspetterebbe che Claude si fidi di un file, come un AGENTS.md o un CLAUDE.md che altre persone possono modificare, o di una memoria salvata. In caso contrario, invia il suo testo solo in un blocco tool_result, inclusa la prima versione. Per il motivo, consulta Prompt injection indiretta.

Non inserire tale testo in un messaggio di sistema o nel testo di un messaggio utente e, nelle nuove conversazioni, non inserirlo in system.

Quando carichi un file di questo tipo o quando cambia, chiedi a Claude di leggerlo con uno strumento e non includere il suo testo. Oppure, dopo il messaggio utente successivo, aggiungi tu stesso la chiamata allo strumento e il suo risultato: un messaggio assistant con un blocco tool_use, poi un messaggio user il cui blocco tool_result contiene il testo. Per i passaggi, consulta Scrivi tu stesso la chiamata allo strumento.

Un file che il tuo utente si aspetta che Claude segua può andare in un messaggio utente. Un file di istruzioni che controlli solo tu può andare in un messaggio di sistema: caricalo una volta e aggiungi in coda ogni versione aggiornata.

Aggiorna la data, i file o altro contesto

Costruisci system e il primo messaggio una sola volta, e inviali invariati in ogni richiesta.

Inserisci un valore aggiornato in un proprio blocco di testo del messaggio utente che stai per inviare, dopo eventuali risultati degli strumenti:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Environment update: the current branch is now release-2." },
    { "type": "text", "text": "Run the tests again." }
  ]
}

Indicalo solo quando cambia e lascialo lì.

Conserva qualsiasi contesto che il tuo codice aggiunge a un messaggio insieme a quel messaggio. Altrimenti la richiesta successiva invia qualcosa di diverso prima dello stesso ragionamento.

Aggiungi, rimuovi o disattiva strumenti

Mantieni tools uguale in ogni richiesta. Aggiungere, modificare o rimuovere uno strumento lì, tranne uno differito, rende non valido il ragionamento già presente nella conversazione, perché tools viene prima di tutto questo. Basta una sola frase riformulata in una descrizione.

Per aggiungere o rimuovere uno strumento, aggiungi in coda un messaggio di sistema con un blocco tool_addition o tool_removal e il beta header per il tuo caso. Fai lo stesso quando si connette un server MCP o un plugin.

Per disattivare gli strumenti per una richiesta, imposta tool_choice: {"type": "none"} e mantieni tools com’era.

Riduci o riassumi i turni più vecchi

Per mantenere i turni recenti con il loro ragionamento, lascia che sia l’API a scrivere il riepilogo con la compattazione su richiesta, rispettando le condizioni per il ragionamento mantenuto. Inizia messages con il blocco di compattazione che restituisce e rimuovi i messaggi che riassume.

Se è il tuo codice a scrivere il riepilogo, o taglia i turni più vecchi senza riepilogo, rimuovi il ragionamento dei turni mantenuti o invia "drop_block". Ogni nuovo taglio rende di nuovo non valido il ragionamento dei turni mantenuti, quindi taglia di rado, a passi ampi. Per cancellare invece i vecchi risultati degli strumenti, usa la modifica del contesto.

Salva, riprendi o dirama una conversazione

Conserva ciò che hai inviato e ciò che hai ricevuto, e invia esattamente quello. Una conversazione ripresa è una normale richiesta successiva: system, tools e i messages precedenti devono avere i valori che avevano. Per una diramazione, inserisci l’istruzione del ramo nel suo primo nuovo messaggio utente, o in un messaggio di sistema dopo di esso. Il ragionamento non può spostarsi in una conversazione con una cronologia diversa: avvia invece quella conversazione da un riepilogo.

Un rilascio che modifica il tuo prompt di sistema o i tuoi strumenti è una modifica nelle conversazioni già in corso. Può esserlo anche la correzione che rende il tuo codice “append-only” (in sola aggiunta). Continua a inviare a ogni conversazione in corso il system e i tools della sua ultima richiesta riuscita, perché il suo ragionamento più recente è stato prodotto dopo quella versione. Tornare a una versione precedente renderebbe non valido quel ragionamento.

Usa system e tools aggiornati nelle nuove conversazioni. Se il rilascio rimuove uno strumento o modifica un’istruzione per motivi di sicurezza, applicalo anche alle conversazioni in corso. Aggiungi in coda un blocco tool_removal o un messaggio di sistema.

Rimuovi segreti, dati personali o testo iniettato

Sicurezza e privacy vengono prima della validità del ragionamento. Se un messaggio contiene un segreto o dati personali che devi eliminare, rimuovi quel testo. Rimuovilo anche da ogni messaggio e riepilogo che lo ripete.

Per un risultato di strumento con istruzioni iniettate, sostituisci il suo contenuto con una breve nota come “Rimosso.” Mantieni il blocco tool_result stesso, perché il suo tool_use ne ha bisogno. Se un blocco di compattazione contiene il testo, elimina il blocco e riparti dal tuo riepilogo.

Poi elimina ogni blocco thinking e redacted_thinking successivo al primo punto in cui è comparso il testo. Se era in system o tools, si tratta di tutti i blocchi. Ogni blocco può ripetere il testo e non puoi leggere né modificare ciò che contiene. Inviare "drop_block" non basta in questo caso, perché lascia quei blocchi nella cronologia salvata. La conversazione prosegue senza quel ragionamento.

Dopo un risultato iniettato, i turni successivi potrebbero aver già agito in base a esso. Controlla le chiamate agli strumenti effettuate da allora e annulla ciò che serve.

Dettagli tecnici

Modi in cui il codice modifica i turni dell’assistente

• Un serializzatore scarta i tipi di blocco che non conosce, oppure riordina, unisce o divide i blocchi. Questo cambia ciò che precede ogni blocco successivo.
• Il codice salta i blocchi di ragionamento che sembrano vuoti. Se li salta tutti, Claude perde quel ragionamento. Se ne salta solo alcuni, il vuoto rende non valido il ragionamento successivo.
• Un tuo parser di stream scarta un blocco di ragionamento che non ha ricevuto testo. Gli helper di streaming dell’SDK lo mantengono.

Ometti il ragionamento

Claude perde il ragionamento che ometti. Ometti i blocchi più vecchi, i più recenti o tutti, ma nessuno nel mezzo. Ogni blocco registra quello dopo cui è stato prodotto, quindi un vuoto rende non validi i blocchi successivi. I blocchi di ragionamento senza altri blocchi tra loro in un turno vengono controllati insieme, quindi ometti tutti o nessuno. Una volta omesso un blocco, continua a ometterlo.

Mentre una chiamata a uno strumento è aperta, rinvia il ragionamento di quel turno, in modo che Claude completi il ciclo con il suo ragionamento.

Le tue istruzioni in un ciclo di strumenti

I messaggi vanno in questo ordine:

[
  {
    "role": "assistant",
    "content": [
      { "type": "thinking", "thinking": "", "signature": "..." },
      {
        "type": "tool_use",
        "id": "toolu_01",
        "name": "run_tests",
        "input": { "path": "tests/" }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "2 failed, 48 passed" }
    ]
  },
  {
    "role": "system",
    "content": "Plan mode is off. You can edit files."
  }
]

Scrivi tu stesso la chiamata allo strumento

Dichiara uno strumento che legge file nella prima richiesta, o aggiungilo in seguito in un messaggio di sistema, e fai rispondere il tuo codice alle chiamate di Claude a esso. Dopo il messaggio utente successivo, aggiungi in coda un messaggio assistant con un blocco tool_use per quello strumento. Subito dopo, aggiungi in coda un messaggio user il cui blocco tool_result ha il tool_use_id corrispondente e contiene il testo del file. Claude risponde dopo:

[
  { "role": "user", "content": "Run the tests again." },
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_app_agents_md_1",
        "name": "read_file",
        "input": { "path": "AGENTS.md" }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_app_agents_md_1",
        "content": "The file's text"
      }
    ]
  }
]

Lascia entrambi al loro posto e aggiungi in coda una nuova coppia, con un nuovo id, per ogni nuova versione.

Le parole del tuo utente, e i valori aggiornati, in un ciclo di strumenti

Se inoltri ciò che il tuo utente ha digitato mentre Claude stava lavorando, aggiungilo prima di inviare il messaggio utente che contiene i blocchi tool_result. Rendilo un blocco di testo dopo l’ultimo tool_result.

Un valore che proviene da te può invece andare in un messaggio di sistema. Dopo i risultati degli strumenti, Claude Sonnet 5.5 e Claude Haiku 5.5 possono ignorare le parole di un utente in un messaggio di sistema considerandole una prompt injection. Claude Sonnet 5.5 può fare lo stesso con le tue istruzioni e i tuoi promemoria se vengono dopo ogni risultato di strumento.

Il messaggio utente con i risultati degli strumenti deve contenere solo blocchi tool_result quando il turno ha anche chiamato uno strumento server che non ha ancora un risultato, o ha usato la chiamata programmatica degli strumenti. In tal caso aggiungi il testo al messaggio utente successivo.

Modelli che non accettano messaggi di sistema

Sulla Claude API, ogni modello con ragionamento preservato accetta messaggi di sistema. Per un modello che non li accetta, consulta Quando un modello non accetta messaggi di sistema.

Invia un promemoria per un solo turno

Invia un promemoria come messaggio di sistema limitato al turno: imposta clear_at: "next_user_message" e invia il beta header mid-conversation-system-clear-at-2026-08-21. Va dopo il messaggio utente che contiene i blocchi tool_result:

{
  "role": "system",
  "clear_at": "next_user_message",
  "content": "Run the linter before you report that a task is done."
}

Al messaggio utente successivo, anche uno con soli blocchi tool_result, l’API lo disattiva, quindi Claude smette di leggerlo. Su Claude Sonnet 5.5, non inviarne uno dopo ogni risultato di strumento. Mantieni ogni promemoria nei tuoi messages, disattivato o meno, a meno che non contenga qualcosa che devi rimuovere. Rimuoverne o riformularne uno rende non valido il ragionamento successivo.

Senza l’header, invia un normale messaggio di sistema e lascialo al suo posto. Non si disattiva mai, quindi i promemoria si accumulano. Su un modello che non accetta messaggi di sistema, usa un blocco di testo nel messaggio utente.

Quale blocco e quale beta header richiede una modifica agli strumenti

Per le piattaforme che accettano ciascun header, consulta Messaggi di sistema e modifiche agli strumenti a metà conversazione.

• Se conosci tutti gli strumenti fin dall’inizio: Dichiarali tutti nella prima richiesta, con defer_loading: true su quelli che offri in seguito. Poi indica lo strumento per nome in un blocco tool_addition o tool_removal di un messaggio di sistema. Beta header: inline-tools-2026-09-15 o mid-conversation-tool-changes-2026-07-01.
• Se vieni a conoscenza di uno strumento in seguito, o ne hai uno il cui schema cambia: Definisci lo strumento in un blocco tool_addition di un messaggio di sistema. Beta header: inline-tools-2026-09-15.
• Se vieni a conoscenza di uno strumento in seguito, su una piattaforma senza l’header inline-tools-2026-09-15: Aggiungi lo strumento alla fine di tools con defer_loading: true, il che non costituisce una modifica, poi offrilo per nome. Beta header: mid-conversation-tool-changes-2026-07-01.
• Se connetti in ritardo un server MCP tramite il connettore MCP, sulla Claude API: Definisci il suo mcp_toolset in un blocco tool_addition. Beta header: inline-tools-2026-09-15 e mcp-client-2026-09-15.

Se l’elenco degli strumenti di un server MCP può cambiare, consulta Fissa l’elenco degli strumenti di un server MCP.

Questo messaggio di sistema offre per nome uno strumento dichiarato e ne definisce un altro, il che richiede inline-tools-2026-09-15:

{
  "role": "system",
  "content": [
    {
      "type": "tool_addition",
      "tool": { "type": "tool_reference", "name": "search_tickets" }
    },
    {
      "type": "tool_addition",
      "tool": {
        "type": "tool_definition",
        "definition": {
          "name": "get_weather",
          "description": "Get the current weather in a city.",
          "input_schema": {
            "type": "object",
            "properties": { "city": { "type": "string" } },
            "required": ["city"]
          }
        }
      }
    }
  ]
}

Strumenti con defer_loading e l’errore 400 che lo nomina

Uno strumento con defer_loading: true resta fuori dal contesto di Claude e dal “prefix check” (controllo del prefisso) finché un messaggio o un risultato di ricerca di strumenti non vi fa riferimento. Fino ad allora, aggiungerlo, aggiornarlo o rimuoverlo non costituisce una modifica. Dopo, sì. Anche attivare o disattivare defer_loading conta come modifica di tools.

Dichiara almeno uno strumento non differito, altrimenti la richiesta può ricevere un errore 400 che nomina defer_loading.

Accorcia o cancella vecchi risultati e immagini

Accorcia o riduci la risoluzione di un risultato di strumento o di un’immagine prima di inviarli la prima volta. Se il tuo codice cancella, accorcia o ricodifica qualcosa che ha già inviato, il ragionamento successivo diventa non valido. Per cancellare in seguito vecchi risultati degli strumenti, incluse eventuali immagini al loro interno, usa la modifica del contesto. Invia context_management con una modifica di tipo clear_tool_uses_20250919 e il beta header context-management-2025-06-27. Per la richiesta completa e le sue opzioni, consulta Modifica del contesto.

File inviati tramite URL

Per un file tramite URL, l’API confronta i byte che ha recuperato. Quindi, quando un URL firmato scade, uno nuovo per lo stesso file va bene. Se il contenuto dietro un URL può cambiare, invia un file_id o base64 fin dalla prima richiesta.

Se il tuo codice riassume o taglia i turni più vecchi

Dopo un tuo riepilogo o taglio, il ragionamento di un turno mantenuto non supera il controllo del prefisso, perché i messaggi dopo cui era stato prodotto non ci sono più. Rimuovi quel ragionamento, oppure invia "drop_block". Claude legge comunque il turno senza di esso.

Librerie, proxy e gateway

Se le richieste di altre persone passano attraverso il tuo codice, le tue riscritture modificano la loro cronologia, e potrebbero non essere in grado di vedere o correggere quelle modifiche. Non nascondere l’errore 400. Se esegui un recupero per conto del chiamante, comunicalo, perché la sua cronologia contiene ancora la modifica.

• Inoltra i valori anthropic-beta e thinking.block_binding così come sono stati inviati. Se il tuo gateway consente solo campi noti, aggiungi thinking.block_binding e il valore di header thinking-binding-controls-2026-08-01, altrimenti i tuoi utenti non possono scegliere "drop_block".
• Non rimuovere il beta header inoltrando l’impostazione. Quella richiesta riceve un errore 400.
• Restituisci al chiamante i blocchi di ragionamento il cui testo è vuoto e l’array input_transformations.
• Lascia un messaggio role: "system" dove si trova. Spostarlo in system rende non valido il ragionamento già presente nella conversazione.
• Esegui i test con prefix_mismatch_behavior impostato su "error", che restituisce l’errore su ogni modello con ragionamento preservato.

Passaggi successivi