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 nella conversazione. Quella posizione è ottima per la cache dei prompt: il prompt di sistema fa parte del prefisso stabile, quindi i turni successivi trovano corrispondenza nella cache. È invece una posizione inadeguata per istruzioni di cui scopri di aver bisogno solo nel corso 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 memorizzato nella cache rimane invariato, quindi la richiesta successiva continua a leggerlo dalla cache, e la nuova istruzione viene comunque applicata come istruzione di sistema anziché come normale testo dell'utente.

Questa pagina tratta due funzionalità: i messaggi di sistema a metà conversazione, che sono disponibili a livello generale, 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 hashing, 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 l'equivalente per gli strumenti dei messaggi di sistema a metà conversazione. Invece di fissare l'elenco degli strumenti per l'intera durata della conversazione, modifichi quali strumenti vengono offerti al modello tra un turno e l'altro: dichiara l'insieme completo degli strumenti in tools all'inizio, quindi 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 stesso non cambia mai, quindi il prefisso memorizzato nella 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 poi. Il campo tool di ciascun blocco fa riferimento a uno strumento anziché definirne uno: {"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 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 memorizzato nella 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 viene ancora utilizzata.
        {
            "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 utilizzarle, 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, sull'API di Claude, 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 cache hit richiede che il prefisso corrisponda esattamente a una richiesta recente, byte per byte, fino al punto di interruzione della cache.

Questo ordinamento significa che il campo system di primo livello si trova quasi all'inizio del prefisso sottoposto a hashing. Qualsiasi modifica ad 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 memorizzato nella cache dopo di esso.

I messaggi di sistema a metà conversazione ti permettono 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:

• Modifiche a policy o persona a metà sessione. Una lunga sessione agentica necessita di un nuovo vincolo ("d'ora in poi, scrivi tutto l'SQL come query parametrizzate") dopo decine di turni memorizzati nella cache. Aggiungerlo al campo system di primo livello comporterebbe la rielaborazione dell'intera cronologia.
• Contesto per turno che deve essere autorevole. Vuoi inserire 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 memorizzato nella cache.
• Cambiamenti di stato osservati dalla tua applicazione. La tua applicazione rileva 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, 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. Trasmetterlo come messaggio di sistema dopo il risultato dello strumento successivo 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 di seguito.
• Cambi di modalità che concedono autorizzazioni 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 multi-agente, con un breve promemoria ogni alcuni turni e un avviso di uscita quando la modalità viene disattivata. Per un esempio pratico, 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 dell'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 per le istruzioni che diventano rilevanti solo in seguito, o che vuoi aggiungere senza invalidare il prefisso memorizzato nella 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 fin qui,
    # 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 rende conto a metà sessione che tutti i suggerimenti devono
        # anche rispettare la rigorosa policy di tipizzazione del team. Aggiungere
        # l'istruzione qui mantiene i turni precedenti identici byte per byte, così
        # il prefisso memorizzato 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 punto di interruzione esplicito), nulla viene memorizzato nella cache e ogni richiesta paga il prezzo normale dei token di input per l'intera conversazione. Con la cache abilitata, l'aggiunta del messaggio di sistema lascia invariati i turni già memorizzati nella cache, quindi la richiesta che trasporta la nuova istruzione continua a leggerli dalla cache invece di elaborarli di nuovo. La cache richiede inoltre che la conversazione raggiunga la lunghezza minima del prompt memorizzabile nella 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 strumento server), e deve essere l'ultima voce in messages oppure essere immediatamente seguito da un turno assistant. Un messaggio user che trasporta 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ò trasmettere 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 piuttosto che come un comando che prevale sull'utente. Dichiara 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 l'utente ha detto" è meno efficace che dichiarare cosa è cambiato.

Questo pattern serve per trasmettere input dall'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 viene attivata 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.
• Memorizza nella cache il prefisso stabile come di consueto. 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 memorizzato nella cache, non modifica l'hash del prefisso e la cache continua a trovare corrispondenza.
• Un messaggio di sistema a metà conversazione è esso stesso memorizzabile nella 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 evolversi, 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 trasporta blocchi tool_result) o un turno assistant che termina con un risultato di strumento server, e deve precedere un turno assistant o terminare l'array. Non può trovarsi tra un blocco tool_use e il suo tool_result. Posizionarlo altrove restituisce un errore 400.
• Non è un luogo per contenuti non attendibili. Claude tratta il contenuto di sistema come istruzioni dell'operatore e le 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