Messaggi di sistema e modifiche agli strumenti a metà conversazione

Le istruzioni di sistema normalmente risiedono nel campo system di primo livello, prima di ogni messaggio della conversazione. Quella posizione è ottima per la cache dei prompt: il prompt di sistema fa parte del prefisso stabile, quindi i turni successivi ottengono un hit della cache. È una posizione scadente per le istruzioni di cui scopri di avere 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.

Questa pagina copre due funzionalità: i messaggi di sistema a metà conversazione, che sono generalmente disponibili, e le modifiche agli strumenti a metà conversazione, una beta introdotta con Claude Opus 5 che applica lo stesso approccio all'array tools.



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, una beta introdotta con Claude Opus 5, 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 in anticipo l'intero set di strumenti in tools, poi usa i blocchi tool_addition e tool_removal per offrire uno strumento al modello, o ritirarlo, da un punto specifico della conversazione in poi. 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 mescolati 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 poi. Il campo tool di ciascun blocco fa riferimento a uno strumento anziché definirlo: {"type": "tool_reference", "name": "..."} nomina uno strumento dichiarato nell'array tools della richiesta, e gli strumenti del connettore MCP possono essere referenziati individualmente con mcp_tool_reference (server_name e name) o come intero set di strumenti 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 nascosto finché un blocco tool_addition non lo rende disponibile. tool_addition ripropone 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 viene 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. Sono disponibili su Claude Fable 5, Claude Mythos 5, Claude Opus 4.8 e Claude Opus 5, sulla Claude API, Amazon Bedrock e Google Cloud.



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 hit della cache richiede che il prefisso corrisponda esattamente a una richiesta recente, byte per byte, fino al punto di interruzione della cache.

Quell'ordinamento significa che il campo system di primo livello si trova molto vicino all'inizio del prefisso sottoposto a hash. Qualsiasi modifica a esso, 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 che lo segue.

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:

• Cambiamenti di policy o persona a metà sessione. Una lunga sessione agentica ha bisogno di un nuovo vincolo ("d'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 una modifica alla disponibilità degli strumenti con peso a livello di sistema, e cambia troppo spesso per risiedere nel prefisso in cache.
• Cambiamenti di stato che la tua applicazione osserva. La tua applicazione nota qualcosa che Claude dovrebbe trattare come un fatto a livello di operatore: file modificati su disco, l'utente ha attivato un'impostazione di approvazione automatica, gli strumenti disponibili sono cambiati, o il budget di token rimanente è sceso sotto una soglia.
• Input dell'utente che non dovrebbe interrompere un ciclo agentico. Un utente digita un follow-up mentre Claude sta ancora eseguendo strumenti per la richiesta precedente. Inoltrarlo come messaggio di sistema dopo il risultato dello strumento successivo permette a Claude di incorporare 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 più avanti.
• 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 diversi turni e un avviso di uscita quando la modalità viene disattivata. Per un esempio pratico, vedi Costruisci 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 cache miss derivante dalla 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 poi. 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 alle istruzioni che diventano rilevanti solo in seguito, o che vuoi aggiungere senza invalidare il prefisso in cache.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    # Cache dei prompt automatica: ogni richiesta memorizza nella cache la conversazione fino a quel punto,
    # e la richiesta successiva legge dalla cache il prefisso rimasto 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 rende conto a metà sessione che tutti i suggerimenti devono
        # rispettare anche la rigorosa policy di tipizzazione del team. Aggiungere
        # l'istruzione qui mantiene i turni precedenti identici byte per byte, quindi il
        # prefisso memorizzato nella 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 un campo cache_control (automatico o un punto di interruzione 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 porta 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 è al di sotto di tale soglia, 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 immediatamente seguito 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, così il nuovo contesto viene 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 piuttosto che come un comando che prevale sull'utente. Dichiara il fatto ("è arrivato un 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 agire contro l'utente, e quella protezione si applica anche al ruolo di sistema, quindi un linguaggio come "ignora ciò che l'utente ha detto" è meno efficace rispetto a dichiarare cosa è cambiato.

Questo pattern serve per inoltrare l'input dell'utente finale della conversazione stessa. Non usarlo per passare output di strumenti, documenti recuperati o altri contenuti di terze parti; mantieni quel contenuto nei blocchi tool_result (vedi Limitazioni).



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 punto di interruzione esplicito su un blocco di contenuto. Un messaggio di sistema a metà conversazione non crea da solo una voce di cache, e senza la cache abilitata non ci sono risparmi da preservare.
• Metti in cache il prefisso stabile come al solito. Posiziona cache_control sull'ultimo blocco che rimane invariato 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 punto di interruzione. Poiché viene dopo il prefisso in cache, non cambia l'hash del prefisso e la cache continua a fare hit.
• Un messaggio di sistema a metà conversazione è esso stesso memorizzabile in cache. Una volta che è nella conversazione, diventa parte della cronologia stabile. Al turno successivo puoi spostare il tuo punto di interruzione della cache oltre di esso (o affidarti alla cache automatica per farlo) 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 poi. Se l'istruzione deve evolvere, aggiungi un nuovo messaggio di sistema invece di riscrivere quello vecchio. I messaggi di sistema consecutivi sono accettati e trattati come un'unica sezione di sistema, che segue la stessa regola di posizionamento nel suo insieme.



Limitazioni

• Non per il primo messaggio. Un messaggio system 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 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.
• 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.



Risorse correlate