Messaggi di sistema a metà conversazione

Le istruzioni di sistema risiedono normalmente nel campo system di primo livello, prima di ogni messaggio nella conversazione. Questa 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.

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 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 memorizzato nella cache che lo segue.

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 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 deve 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 consente 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 funzionalità 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 Creare 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 istruzioni che devono applicarsi all'intera conversazione. Riserva i messaggi di sistema a metà conversazione per 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-4-8",
    max_tokens=1024,
    # Cache dei prompt automatica: ogni richiesta memorizza nella cache la conversazione fino a quel punto,
    # e la richiesta successiva legge il prefisso invariato dalla cache.
    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.",
        },
    ],
)

print(response.content[0].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 rimane al di sotto di tale soglia, quindi cache_creation_input_tokens e cache_read_input_tokens restano 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 uso 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 è valido: in un ciclo agentico puoi posizionare il messaggio di sistema subito dopo i risultati degli strumenti, prima del turno successivo di Claude. L'unica posizione non consentita è tra un blocco tool_use di assistant e il tool_result che gli risponde.

Posizionamento dopo i risultati degli strumenti

In un ciclo agentico, il messaggio di sistema va dopo il messaggio user che fornisce 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 anziché 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 a istruzioni che sembrano agire contro l'utente, e questa 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 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 anziché riscrivere quello vecchio. Messaggi di sistema consecutivi non sono consentiti; unisci le istruzioni in un unico messaggio o attendi il turno utente successivo prima di aggiungerne un altro.

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 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 uso 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 posto 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