Si dice spesso in ingegneria che "Cache Rules Everything Around Me", e la stessa regola vale per gli agenti.
I prodotti agentici a lunga esecuzione come Claude Code sono resi possibili dal prompt caching, che ci permette di riutilizzare la computazione delle interazioni precedenti, riducendo significativamente latenza e costi.
Cos'è il prompt caching, come funziona e come lo si implementa tecnicamente? Leggi di più nell'articolo di @RLanceMartin sul prompt caching e il lancio del nostro nuovo auto-caching.
In Claude Code, abbiamo costruito l'intero sistema attorno al prompt caching. Un tasso di hit elevato del prompt cache riduce i costi e ci aiuta a offrire limiti di velocità più generosi nei nostri piani di abbonamento; per questo monitoriamo il tasso di hit del prompt cache e dichiariamo SEV se è troppo basso.
Queste sono le lezioni (spesso controintuitive) che abbiamo imparato ottimizzando il prompt caching su larga scala.
Organizza il tuo Prompt per il Caching
Il prompt caching funziona tramite il matching del prefisso: l'API memorizza nella cache tutto ciò che va dall'inizio della richiesta fino a ogni breakpoint cache_control. Questo significa che l'ordine in cui inserisci gli elementi è fondamentale: vuoi che quante più richieste possibile condividano lo stesso prefisso.
Il modo migliore per farlo è mettere il contenuto statico per primo e quello dinamico per ultimo. Per Claude Code, la struttura è:
- System prompt statico e Strumenti (memorizzati globalmente nella cache)
- Claude.MD (memorizzato nella cache all'interno di un progetto)
- Contesto della sessione (memorizzato nella cache all'interno di una sessione)
- Messaggi della conversazione
In questo modo, massimizziamo il numero di sessioni che condividono hit della cache.
Ma questa struttura è sorprendentemente fragile! Esempi di come abbiamo rotto quest'ordine in passato includono: inserire un timestamp dettagliato nel system prompt statico, mescolare in modo non deterministico l'ordine delle definizioni degli strumenti, aggiornare i parametri degli strumenti (ad esempio, quali agenti AgentTool può chiamare), ecc.
Usa i Messaggi per gli Aggiornamenti
Può capitare che le informazioni inserite nel prompt diventino obsolete, ad esempio se hai l'ora esatta o se l'utente modifica un file. Potresti essere tentato di aggiornare il prompt, ma ciò causerebbe un cache miss e potrebbe rivelarsi piuttosto costoso per l'utente.
Valuta se puoi invece trasmettere queste informazioni tramite messaggi al turno successivo. In Claude Code, aggiungiamo un tag <system-reminder> nel messaggio utente successivo o nel risultato dello strumento con le informazioni aggiornate per il modello (ad esempio, "ora è mercoledì"), il che aiuta a preservare la cache.
Non Cambiare Modello a Metà Sessione
I prompt cache sono specifici per ogni modello, e questo può rendere il calcolo del prompt caching piuttosto controintuitivo.
Se sei a 100.000 token in una conversazione con Opus e vuoi fare una domanda piuttosto semplice, sarebbe in realtà più costoso passare a Haiku piuttosto che far rispondere Opus, perché dovremmo ricostruire il prompt cache per Haiku.
Se devi cambiare modello, il modo migliore è farlo tramite sottoagenti, dove Opus preparerebbe un messaggio di "passaggio di consegne" a un altro modello sul compito da svolgere. Lo facciamo spesso con gli agenti Explore in Claude Code, che utilizzano Haiku.
Non Aggiungere o Rimuovere Mai Strumenti a Metà Sessione
Cambiare il set di strumenti nel bel mezzo di una conversazione è uno dei modi più comuni per rompere il prompt caching. Sembra intuitivo: dovresti dare al modello solo gli strumenti che pensi servano in quel momento. Ma poiché gli strumenti fanno parte del prefisso memorizzato nella cache, aggiungere o rimuovere uno strumento invalida la cache per l'intera conversazione.
Plan Mode — Progettato Intorno alla Cache
La Plan Mode è un ottimo esempio di come progettare le funzionalità tenendo conto dei vincoli del caching. L'approccio intuitivo sarebbe: quando l'utente attiva la Plan Mode, sostituisci il set di strumenti con solo strumenti di sola lettura. Ma questo romperebbe la cache.
Invece, manteniamo tutti gli strumenti nella richiesta in ogni momento e usiamo EnterPlanMode e ExitPlanMode come strumenti essi stessi. Quando l'utente attiva la plan mode, l'agente riceve un messaggio di sistema che spiega che è in plan mode e quali sono le istruzioni — esplora il codebase, non modificare file, chiama ExitPlanMode quando il piano è completo. Le definizioni degli strumenti non cambiano mai.
Questo ha un ulteriore vantaggio: poiché EnterPlanMode è uno strumento che il modello può chiamare da solo, può entrare autonomamente in plan mode quando rileva un problema complesso, senza rompere la cache.
Tool Search — Rimanda Invece di Rimuovere
Lo stesso principio si applica alla nostra funzionalità di ricerca degli strumenti. Claude Code può avere decine di strumenti MCP caricati e includerli tutti in ogni richiesta sarebbe costoso. Ma rimuoverli a metà conversazione romperebbe la cache.
La nostra soluzione: defer_loading. Invece di rimuovere gli strumenti, inviamo stub leggeri — solo il nome dello strumento, con defer_loading: true — che il modello può "scoprire" tramite uno strumento ToolSearch quando necessario. Gli schemi completi degli strumenti vengono caricati solo quando il modello li seleziona. Questo mantiene stabile il prefisso memorizzato nella cache: gli stessi stub sono sempre presenti nello stesso ordine.
Fortunatamente, puoi usare lo strumento di ricerca tramite la nostra API per semplificare questo processo.
Forking del Contesto — Compattazione
La compattazione è ciò che accade quando si esaurisce la finestra di contesto. Riassumiamo la conversazione fino a quel punto e avviamo una nuova sessione con quel riassunto.
Sorprendentemente, la compattazione presenta molti casi limite con il prompt caching che possono essere controintuitivi.
In particolare, quando compattiamo, dobbiamo inviare l'intera conversazione al modello per generare un riassunto. Se questa è una chiamata API separata con un system prompt diverso e senza strumenti (che è l'implementazione semplice), il prefisso memorizzato nella cache della conversazione principale non corrisponde per niente. Payerai il prezzo pieno per tutti quei token di input, aumentando drasticamente il costo per l'utente.
La Soluzione — Forking Cache-Safe
Quando eseguiamo la compattazione, usiamo esattamente lo stesso system prompt, contesto utente, contesto di sistema e definizioni degli strumenti della conversazione principale. Prepariamo i messaggi della conversazione principale e poi aggiungiamo il prompt di compattazione come nuovo messaggio utente alla fine.
Dal punto di vista dell'API, questa richiesta appare quasi identica all'ultima richiesta della conversazione principale — stesso prefisso, stessi strumenti, stessa cronologia — quindi il prefisso memorizzato nella cache viene riutilizzato. Gli unici nuovi token sono il prompt di compattazione stesso.
Questo significa comunque che dobbiamo salvare un "buffer di compattazione" per avere spazio sufficiente nella finestra di contesto per includere il messaggio compattato e i token di output del riassunto.
La compattazione è complessa, ma fortunatamente non devi imparare queste lezioni da solo — basandoci su quanto appreso da Claude Code, abbiamo integrato la compattazione direttamente nell'API, così puoi applicare questi schemi nelle tue applicazioni.
Lezioni Apprese
- Il prompt caching è un match di prefisso. Qualsiasi cambiamento in qualsiasi punto del prefisso invalida tutto ciò che viene dopo. Progetta l'intero sistema attorno a questo vincolo. Metti a posto l'ordine e la maggior parte del caching funziona da sola.
- Usa i messaggi invece di modificare il system prompt. Potresti essere tentato di modificare il system prompt per cose come attivare la plan mode, cambiare la data, ecc., ma sarebbe meglio inserire queste informazioni nei messaggi durante la conversazione.
- Non cambiare strumenti o modelli a metà conversazione. Usa gli strumenti per modellare i cambi di stato (come la plan mode) invece di modificare il set di strumenti. Rimanda il caricamento degli strumenti invece di rimuoverli.
- Monitora il tuo tasso di hit della cache come monitori il tempo di attività. Interveniamo sulle rotture della cache e le trattiamo come incidenti. Alcuni punti percentuali di cache miss possono influenzare drasticamente costi e latenza.
- Le operazioni di forking devono condividere il prefisso del genitore. Se devi eseguire una computazione secondaria (compattazione, riassunto, esecuzione di skill), usa parametri identici e cache-safe per ottenere hit della cache sul prefisso del genitore.
Claude Code è stato costruito attorno al prompt caching fin dal primo giorno; dovresti fare lo stesso se stai costruendo un agente.
