Messaggi di sistema e modifiche agli strumenti a metà conversazione

Le istruzioni di sistema risiedono normalmente nel campo system di primo livello, prima di ogni messaggio della conversazione. Quella posizione è ottima per il prompt caching (cache dei prompt): il "system prompt" (prompt di sistema) fa parte del prefisso stabile, quindi i turni successivi trovano riscontro nella cache. È invece una posizione poco adatta per le istruzioni di cui scopri di aver bisogno solo a metà di una sessione, perché modificare il campo system di primo livello cambia l'inizio stesso del prompt e invalida la cache per tutto ciò che segue.

I messaggi di sistema a metà conversazione colmano questa lacuna. Aggiungi un messaggio {"role": "system"} nel punto della conversazione in cui la nuova istruzione diventa rilevante, invece di modificare il campo system di primo livello. Il prefisso in cache rimane lo stesso, quindi la richiesta successiva lo legge ancora dalla cache, e la nuova istruzione viene comunque applicata come istruzione di sistema anziché come normale testo utente.

Modifiche agli strumenti a metà conversazione

L'array tools si trova ancora prima del campo system di primo livello nel prefisso della richiesta sottoposto a hash, quindi modificarlo invalida la cache dei prompt per l'intera conversazione. Le modifiche agli strumenti a metà conversazione sono la controparte, per gli strumenti, dei messaggi di sistema a metà conversazione. Invece di fissare l'elenco degli strumenti per tutta la durata della conversazione, cambi quali strumenti vengono offerti al modello tra un turno e l'altro: dichiara l'intero set di strumenti in tools fin dall'inizio, poi usa i blocchi tool_addition e tool_removal per offrire uno strumento al modello, o ritirarlo, da un punto specifico della conversazione in avanti. L'array tools in sé non cambia mai, quindi il prefisso in cache rimane intatto.

tool_addition e tool_removal sono blocchi di contenuto nell'array content di un messaggio role: "system", e possono essere combinati con blocchi text nello stesso messaggio. Il messaggio segue le stesse regole di posizionamento di qualsiasi messaggio di sistema a metà conversazione (vedi Limitazioni), e la modifica si applica da quel punto della conversazione in avanti. Il campo tool di ciascun blocco fa riferimento a uno strumento anziché definirlo: {"type": "tool_reference", "name": "..."} indica uno strumento dichiarato nell'array tools della richiesta, e gli strumenti del connettore MCP possono essere referenziati singolarmente con mcp_tool_reference (server_name e name) oppure come intero toolset con mcp_toolset_reference (server_name). Fare riferimento a un nome non dichiarato in tools restituisce un errore 400.

Ogni strumento dichiarato in tools viene offerto al modello dall'inizio della conversazione, a meno che non sia dichiarato con defer_loading: true, che lo mantiene trattenuto finché un blocco tool_addition non lo rende disponibile. tool_addition offre nuovamente anche uno strumento che un precedente tool_removal aveva ritirato.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    betas=["mid-conversation-tool-changes-2026-07-01"],
    # L'intero set di strumenti è dichiarato all'inizio e non cambia mai, quindi il
    # prefisso in cache rimane intatto.
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a location.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"},
                },
                "required": ["location"],
            },
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Say OK.",
        },
        # Ritira get_weather da questo punto in poi. Il blocco fa riferimento
        # allo strumento per nome invece di modificare `tools`, così i turni precedenti restano
        # identici byte per byte e la cache continua a funzionare.
        {
            "role": "system",
            "content": [
                {
                    "type": "tool_removal",
                    "tool": {"type": "tool_reference", "name": "get_weather"},
                },
            ],
        },
    ],
)

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

Le modifiche agli strumenti a metà conversazione sono in beta. Per usarle, includi l'header beta mid-conversation-tool-changes-2026-07-01 nelle tue richieste.

Quando usare un messaggio di sistema a metà conversazione

La cache dei prompt calcola l'hash del prefisso della richiesta in ordine: tools, poi system, poi messages. Un riscontro nella cache richiede che il prefisso corrisponda esattamente, byte per byte, a una richiesta recente fino al breakpoint della cache.

Questo ordinamento significa che il campo system di primo livello si trova quasi all'inizio del prefisso sottoposto a hash. Qualsiasi modifica, anche l'aggiunta di una frase, produce un hash diverso, e la richiesta manca la cache per il prompt di sistema e per ogni messaggio in cache successivo.

I messaggi di sistema a metà conversazione ti permettono invece di aggiungere l'istruzione alla fine della cronologia dei messaggi. Tutto ciò che precede la nuova istruzione rimane invariato, quindi la voce di cache esistente corrisponde ancora, e solo il nuovo messaggio viene elaborato come input nuovo.

Alcune situazioni in cui questo è importante:

• Cambi di policy o di persona a metà sessione. Una lunga sessione agentica ha bisogno di un nuovo vincolo ("da ora in poi, scrivi tutto l'SQL come query parametrizzate") dopo decine di turni in cache. Aggiungerlo al campo system di primo livello rielaborerebbe l'intera cronologia.
• Contesto per turno che deve essere autorevole. Vuoi iniettare una nota di aggiornamento, una scadenza di sessione o un cambiamento nella disponibilità degli strumenti con peso a livello di sistema, e cambia troppo spesso per risiedere nel prefisso in cache.
• Promemoria per turno che non devono accumularsi. Un harness sollecita il modello dopo ogni gruppo di risultati degli strumenti ("richiedi insieme le letture indipendenti", "l'utente non ha tue notizie da un po'") e vuole che il modello veda solo la copia più recente. Un messaggio di sistema limitato al turno viene reso per un turno e poi non costa nulla, senza eliminare nulla dalla cronologia.
• Cambiamenti di stato osservati dalla tua applicazione. La tua applicazione nota qualcosa che Claude dovrebbe trattare come un fatto a livello di operatore: file modificati su disco, l'utente ha attivato o disattivato un'impostazione di approvazione automatica, gli strumenti disponibili sono cambiati, oppure il budget di token rimanente è sceso sotto una soglia.
• Input dell'utente che non deve interrompere un ciclo agentico. Un utente digita un messaggio di follow-up mentre Claude sta ancora eseguendo strumenti per la richiesta precedente. Inoltrarlo come messaggio di sistema dopo il successivo risultato dello strumento permette a Claude di integrare il nuovo input nel lavoro che sta già svolgendo, invece di trattarlo come una nuova richiesta a cui passare. Vedi Posizionamento dopo i risultati degli strumenti.
• Cambi di modalità che concedono permessi permanenti. Una modalità a livello di sessione può usare un messaggio di sistema a metà conversazione per concedere un consenso permanente a una capacità costosa, come l'avvio automatico di flussi di lavoro multiagente, con un breve promemoria ogni tot turni e un avviso di uscita quando la modalità viene disattivata. Per un esempio completo, vedi Costruire una modalità di orchestrazione.

In tutti questi casi potresti inserire l'istruzione in un normale messaggio user, e Claude segue effettivamente le istruzioni che arrivano nei turni utente. La differenza è la priorità: un messaggio user viene trattato come proveniente dall'utente finale, mentre un messaggio system viene trattato come proveniente da te, l'operatore dell'applicazione. Quando i due sono in conflitto, le istruzioni di sistema hanno la precedenza, quindi usa il ruolo system per fatti e vincoli a livello di operatore che devono valere anche se l'utente finale chiede qualcosa di diverso. Un messaggio di sistema a metà conversazione mantiene quella priorità a livello di operatore senza pagare il costo del mancato riscontro in cache dovuto alla modifica del campo system di primo livello.

Come funziona

Aggiungi un messaggio con "role": "system" all'array messages. Usa una stringa semplice o blocchi di contenuto per content, come per un turno user o assistant. L'istruzione si applica da quel punto della conversazione in avanti. Quando le istruzioni sono in conflitto, i messaggi di sistema successivi hanno la precedenza su quelli precedenti, e i messaggi di sistema a metà conversazione hanno la precedenza sul campo system di primo livello per i turni che li seguono.

Puoi comunque impostare il campo system di primo livello per le istruzioni che devono applicarsi all'intera conversazione. Riserva i messaggi di sistema a metà conversazione per le istruzioni che diventano rilevanti solo in seguito, o che vuoi aggiungere senza invalidare il prefisso in cache.

Un messaggio role: "system" può anche contenere output_config.effort per cambiare il livello di effort (impegno) a partire dal turno user successivo. Questa funzionalità è in beta su Claude Fable 5.1, Claude Mythos 5.1 e Claude Opus 5 sulla Claude API e richiede l'header beta mid-conversation-output-config-2026-07-01. Vedi Effort per messaggio.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    # Cache dei prompt automatica: ogni richiesta mette in cache la conversazione finora,
    # e la richiesta successiva legge dalla cache il prefisso invariato.
    cache_control={"type": "ephemeral"},
    system="You are a code review assistant. Be concise.",
    messages=[
        {
            "role": "user",
            "content": "Review process() in utils.py for performance issues.",
        },
        {
            "role": "assistant",
            "content": "The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list.",
        },
        {
            "role": "user",
            "content": "Now review the calling code that invokes process().",
        },
        # Il revisore si accorge a metà sessione che tutti i suggerimenti devono
        # rispettare anche la rigida policy di tipizzazione del team. Aggiungere
        # l'istruzione qui mantiene i turni precedenti identici byte per byte, così il
        # prefisso messo in cache dalla richiesta precedente viene ancora letto dalla cache.
        {
            "role": "system",
            "content": "From now on, every suggestion must include explicit type annotations.",
        },
    ],
)

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

Questo esempio abilita la cache automatica con il campo cache_control di primo livello. La cache dei prompt è opt-in: se una richiesta non ha alcun campo cache_control (automatico o un breakpoint esplicito), nulla viene messo in cache e ogni richiesta paga il normale prezzo dei token di input per l'intera conversazione. Con la cache abilitata, l'aggiunta del messaggio di sistema lascia invariati i turni già in cache, quindi la richiesta che contiene la nuova istruzione li legge ancora dalla cache invece di elaborarli di nuovo. La cache richiede inoltre che la conversazione raggiunga la lunghezza minima del prompt memorizzabile in cache; un esempio breve come questo resta al di sotto, quindi cache_creation_input_tokens e cache_read_input_tokens rimangono a 0 finché la conversazione non cresce.

Un messaggio di sistema a metà conversazione deve seguire immediatamente un turno user (o un turno assistant che termina con un risultato di uno strumento server), e deve essere l'ultima voce in messages oppure essere seguito immediatamente da un turno assistant. Un messaggio user che contiene blocchi tool_result conta: in un ciclo agentico puoi posizionare il messaggio di sistema subito dopo i risultati degli strumenti, prima del turno successivo di Claude. Qualsiasi altra posizione, inclusa quella tra un blocco tool_use di assistant e il tool_result che gli risponde, restituisce un errore 400.

Posizionamento dopo i risultati degli strumenti

In un ciclo agentico, il messaggio di sistema va dopo il messaggio user che consegna i risultati degli strumenti. Questo è anche il punto in cui la tua applicazione può inoltrare l'input che l'utente ha digitato mentre Claude stava lavorando, in modo che il nuovo contesto venga assorbito senza riavviare il turno:

[
  { "role": "user", "content": "Run the test suite and fix any failures." },
  {
    "role": "assistant",
    "content": [{ "type": "tool_use", "id": "toolu_01", "name": "run_tests", "input": {} }]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 passed, 0 failed" }
    ]
  },
  {
    "role": "system",
    "content": "The user sent the following message while you were working: also update the changelog before you finish."
  }
]

Formula il contenuto di sistema come contesto anziché come un comando che prevale sull'utente. Enuncia il fatto ("è arrivato nuovo input dall'utente: X", "il budget di token rimanente è ora Y") e lascia che Claude agisca di conseguenza. Claude è addestrato a resistere alle istruzioni che sembrano andare contro l'utente, e quella protezione si applica anche al ruolo di sistema, quindi un linguaggio come "ignora ciò che ha detto l'utente" è meno efficace rispetto a indicare cosa è cambiato.

Questo schema serve a inoltrare input proveniente dall'utente finale della conversazione stessa. Non usarlo per passare output di strumenti, documenti recuperati o altri contenuti di terze parti; mantieni quei contenuti nei blocchi tool_result (vedi Limitazioni).

Messaggi di sistema limitati al turno

Per limitare un messaggio role: "system" al turno corrente, imposta il suo campo clear_at. Accetta uno di due valori:

• "never" (il valore predefinito): il messaggio viene reso nella sua posizione in ogni richiesta che lo include. Omettere il campo è identico.
• "next_user_message": il messaggio è limitato al turno (turn-scoped). Il suo testo viene reso solo finché nessun messaggio role: "user" lo segue in messages. Un messaggio utente che contiene solo blocchi tool_result conta qui come messaggio utente. Una volta che esiste un messaggio utente successivo, il messaggio viene cancellato (cleared): rimane nell'array ma non rende nulla e non costa token di input, in quella richiesta e in tutte le successive.

I messaggi di sistema limitati al turno sono in beta. Includi l'header beta mid-conversation-system-clear-at-2026-08-21. Senza di esso, clear_at viene rifiutato come campo sconosciuto.

{
  "role": "system",
  "clear_at": "next_user_message",
  "content": "First privately list what you need next; then request every item that doesn't depend on another's result in this one response."
}

L'uso principale è un promemoria per turno in un ciclo di strumenti. Aggiungi il promemoria dopo il messaggio tool_result ogni volta che vuoi che il modello lo veda, e lascia ogni copia precedente dov'è. Il modello vede solo le copie che vengono dopo l'ultimo messaggio utente, quindi il promemoria non si accumula mai. Nulla di precedente in messages cambia, quindi la cache dei prompt continua a corrispondere. Su Claude Fable 5.1 questo mantiene anche validi i blocchi di pensiero successivi: eliminare un promemoria precedente cambierebbe la conversazione prima di quei blocchi e farebbe fallire il controllo della conversazione, mentre un messaggio cancellato rimane nell'array e lascia quella conversazione invariata.

La richiesta seguente è un passo successivo di un ciclo agentico. messages[3] è stato reso nella richiesta precedente, quando era l'ultimo messaggio nell'array. Una volta che esiste messages[5] (un messaggio utente successivo), messages[3] viene cancellato: il messaggio cancellato rimane nell'array, quindi la conversazione prima del blocco di pensiero in messages[4] è invariata, ma il modello non vede più il suo testo. messages[6] e messages[7] vengono entrambi resi, in ordine.

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "messages": [
    { "role": "user", "content": "Fix the failing test." },
    {
      "role": "assistant",
      "content": [
        { "type": "thinking", "thinking": "", "signature": "..." },
        {
          "type": "tool_use",
          "id": "toolu_01",
          "name": "read_file",
          "input": { "path": "test_auth.py" }
        }
      ]
    },
    {
      "role": "user",
      "content": [{ "type": "tool_result", "tool_use_id": "toolu_01", "content": "..." }]
    },
    {
      "role": "system",
      "clear_at": "next_user_message",
      "content": "Request independent reads in one turn."
    },
    {
      "role": "assistant",
      "content": [
        { "type": "thinking", "thinking": "", "signature": "..." },
        {
          "type": "tool_use",
          "id": "toolu_02",
          "name": "read_file",
          "input": { "path": "auth.py" }
        },
        {
          "type": "tool_use",
          "id": "toolu_03",
          "name": "read_file",
          "input": { "path": "tokens.py" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        { "type": "tool_result", "tool_use_id": "toolu_02", "content": "..." },
        {
          "type": "tool_result",
          "tool_use_id": "toolu_03",
          "content": "...",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    {
      "role": "system",
      "clear_at": "next_user_message",
      "content": "Request independent reads in one turn."
    },
    {
      "role": "system",
      "clear_at": "next_user_message",
      "content": "The shell exited with status 137."
    }
  ]
}

Regole per i messaggi limitati al turno:

• Reinvia i messaggi cancellati alla lettera. Un messaggio cancellato fa ancora parte della cronologia della conversazione. Ricostruirlo dallo stato corrente (un nuovo conteggio di token, un timestamp), scartarlo come ridondante o cambiare il suo valore clear_at equivale a modificare un messaggio precedente. La cache dei prompt manca il riscontro da quel punto, e su Claude Fable 5.1 ogni blocco di pensiero prodotto dopo di esso fallisce il controllo della conversazione.
• Solo testo. content è uno o più blocchi text (o una stringa). I blocchi tool_addition e tool_removal restituiscono un errore 400 su un messaggio limitato al turno, e lo stesso vale per output_config. Per quelli usa un messaggio role: "system" separato senza clear_at.
• Nessun cache_control sui suoi blocchi. Un messaggio cancellato non fa mai parte di una chiave di cache, quindi un breakpoint su di esso non potrebbe mai corrispondere. Metti invece il breakpoint sull'ultimo blocco del turno utente precedente, come fa l'esempio. Il campo di cache automatica di primo livello salta i messaggi limitati al turno quando sceglie un breakpoint. Nella richiesta che cancella un messaggio, il prefisso in cache riutilizzabile termina al turno utente che lo precede, quindi viene rielaborato solo l'unico turno assistant tra quel messaggio e il nuovo messaggio utente.
• Le regole di posizionamento si applicano comunque, cancellato o meno. Un messaggio limitato al turno deve seguire un turno user (o un turno assistant che termina con un risultato di uno strumento server) e precedere un turno assistant o chiudere l'array, come qualsiasi messaggio di sistema a metà conversazione. Uno che chiude l'array viene sempre reso. Uno seguito direttamente da un altro messaggio user è un errore 400, non un messaggio cancellato: metti tutti i risultati di un giro di strumenti in un unico messaggio utente e i promemoria dopo di esso.
• I turni assistant non lo cancellano. Un turno assistant precompilato o in pausa dopo il messaggio, o un ciclo di strumenti lato server, non aggiunge alcun messaggio utente, quindi il messaggio viene ancora reso in quella continuazione. Per mantenere un promemoria visibile durante un ciclo di strumenti lato client, aggiungilo di nuovo dopo ogni messaggio tool_result.
• Il conteggio dei token segue ciò che viene reso. Un messaggio cancellato non aggiunge nulla a usage.input_tokens né a un conteggio dei token.
• Cronologia importata. In una trascrizione che costruisci in un unico passaggio (esempi few-shot, una conversazione migrata), un messaggio limitato al turno che ha già un turno assistant e un messaggio utente dopo di sé è cancellato fin dalla prima richiesta e non viene mai reso. Questo è lo stato corretto per un promemoria per turno che stai trasferendo. Lascia clear_at non impostato solo su un messaggio che il modello deve vedere in ogni richiesta.

Gli errori di validazione sono:

messages.3.clear_at: Extra inputs are not permitted
messages.3.clear_at: clear_at is only permitted on role 'system' messages
messages.3.clear_at: Input should be 'next_user_message' or 'never'
messages.3: a turn-scoped system message supports text blocks only (clear_at: 'next_user_message')
messages.3: output_config is not permitted on a turn-scoped system message (clear_at: 'next_user_message')
messages.3.content.0: cache_control is not permitted on a turn-scoped system message (clear_at: 'next_user_message')

Il primo è l'errore restituito senza l'header beta. Su Amazon Bedrock e Google Cloud, passa il valore beta come descritto in Header beta.

Tramite gli SDK, imposta clear_at sulla voce role: "system" in messages e invia l'header beta. L'esempio seguente aggiunge un promemoria limitato al turno dopo il turno utente; nella richiesta successiva, una volta che esiste un messaggio utente successivo, il promemoria rimane nell'array ma non viene più reso:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Draft a short status update on the database migration for the team channel.",
        },
        # Promemoria limitato al turno: viene mostrato per questo turno, poi rimosso quando esiste un messaggio utente successivo.
        {
            "role": "system",
            "clear_at": "next_user_message",
            "content": "The reader is on call: keep this reply under 50 words.",
        },
    ],
    betas=["mid-conversation-system-clear-at-2026-08-21"],
)

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

Combinazione con la cache dei prompt

I messaggi di sistema a metà conversazione e la cache dei prompt sono progettati per essere usati insieme:

• Abilita la cache esplicitamente. La cache avviene solo quando la richiesta include cache_control, sia il campo di cache automatica di primo livello sia un breakpoint esplicito su un blocco di contenuto. Un messaggio di sistema a metà conversazione non crea di per sé una voce di cache, e senza la cache abilitata non ci sono risparmi da preservare.
• Metti in cache il prefisso stabile come di consueto. Posiziona cache_control sull'ultimo blocco che rimane uguale tra le richieste, che sia la fine del campo system di primo livello, la fine delle definizioni degli strumenti o un punto stabile nella cronologia dei messaggi.
• Aggiungi il messaggio di sistema dopo il breakpoint. Poiché viene dopo il prefisso in cache, non cambia l'hash del prefisso e la cache trova ancora riscontro.
• Un messaggio di sistema a metà conversazione è esso stesso memorizzabile in cache. Una volta nella conversazione, diventa parte della cronologia stabile. Al turno successivo puoi spostare il breakpoint della cache oltre di esso (o affidarti alla cache automatica perché lo faccia) e il messaggio di sistema viene letto dalla cache come qualsiasi altro turno.

Evita di modificare o rimuovere un messaggio di sistema a metà conversazione che è già stato inviato. Come qualsiasi altra modifica ai messaggi precedenti, ciò invalida la cache da quel punto in avanti. Su Claude Fable 5.1 invalida anche i blocchi di pensiero in ogni turno assistant successivo. Per indicazioni che devono applicarsi a un solo turno, usa un messaggio di sistema limitato al turno e lascialo al suo posto. Se l'istruzione deve evolvere, aggiungi un nuovo messaggio di sistema anziché riscrivere quello vecchio. I messaggi di sistema consecutivi sono accettati e trattati come un'unica sezione di sistema, che segue nel suo insieme la stessa regola di posizionamento.

Limitazioni

• Non per il primo messaggio. Un messaggio system che contiene contenuto non può essere la prima voce in messages. Usa il campo system di primo livello per le istruzioni che si applicano fin dall'inizio.
• Il posizionamento è vincolato. Un messaggio system che contiene contenuto (blocchi text, tool_addition o tool_removal) deve seguire immediatamente un turno user (incluso un turno user che contiene blocchi tool_result) o un turno assistant che termina con un risultato di uno strumento server, e deve precedere un turno assistant o chiudere l'array. Non può trovarsi tra un blocco tool_use e il suo tool_result. Posizionarlo altrove restituisce un errore 400. Un messaggio con content vuoto che imposta solo output_config.effort non rende nulla nella sua posizione ed è accettato ovunque in messages, anche come primo o tra un turno assistant e un turno user. I messaggi system consecutivi vengono valutati insieme, quindi aggiungere un messaggio con testo accanto a uno con solo effort fa sì che l'intero gruppo segua la regola del contenuto.
• I messaggi limitati al turno sono solo testo e vanno reinviati alla lettera. Un messaggio clear_at: "next_user_message" non contiene tool_addition, tool_removal, output_config né cache_control, e una volta cancellato deve rimanere in messages byte per byte nelle richieste successive. Vedi Messaggi di sistema limitati al turno.
• Non è un posto per contenuti non attendibili. Claude tratta il contenuto di sistema come istruzioni dell'operatore e lo segue. Non inserire testo proveniente dall'esterno della conversazione, come output grezzo di strumenti, documenti recuperati o contenuti web, direttamente in un messaggio di sistema; farlo conferisce a quel testo autorità a livello di operatore. Mantieni quei dati nei blocchi tool_result e continua a seguire Mitigare jailbreak e prompt injection.

Correlati