Prompt caching workspace-level di Anthropic: perché i tuoi agenti costano troppo e come diagnosticare le cache mancate

Il 28 aprile 2026 ho fatto un audit della pipeline di automazione AI di un cliente del settore servizi B2B che ha 12 agent Claude in produzione e una bolletta API mensile sopra i 4.500 dollari. Sul mio Hetzner CCX33 (8 vCPU AMD EPYC 9454P, 32 GB RAM DDR5) ho instrumentato 24 ore di traffico con un wrapper di logging che cattura ogni call, registra cache_creation_input_tokens e cache_read_input_tokens separatamente da input_tokens standard, e calcola il rapporto cache-hit per ognuno dei 12 agent. Il risultato è stato uno schiaffo: il cache-hit medio era del 31%, contro un teorico potenziale del 92% misurato sul system prompt e tool list che il cliente aveva (lunghi, stabili, perfetti per caching). Il delta fra 31% reale e 92% potenziale corrispondeva a oltre 2.700 dollari al mese di sprecato budget API, su una bolletta totale di 4.500. Il cliente non sapeva nemmeno di avere il problema, perché Anthropic non manda alert quando le cache sono mancate.

Dal febbraio 2026 il prompt caching workspace-level di Anthropic è disponibile su tutti i modelli Claude (Opus 4.7, Sonnet 4.6, Haiku 4.5) e fattura i token cache-hit al 10% del prezzo input standard. Su Opus 4.7 il prezzo input è $5/M, quindi cache-hit costa $0.50/M. Su un agent che ha 8.000 token di system prompt + tool list invariata fra le chiamate, e che fa 200 chiamate al giorno, il delta cost fra 0% cache-hit e 90% cache-hit è circa 540 dollari al mese. Moltiplicato per 12 agent del cliente sopra, sono i 2.700 dollari/mese che ho misurato. La buona notizia è che il delta si recupera tutto se sai dove guardare. Quello che porto sotto è la checklist sistematica di nove punti che applico nei progetti consulenziali per portare il cache-hit dal 30% al 90% di un agent Claude tipico, ognuno con criterio operativo di verifica e fix concreto.

Cosa è il prompt caching workspace-level e come si verifica davvero

Il prompt caching Anthropic si attiva a livello di prefix del prompt: i token che precedono un blocco contrassegnato come "ephemeral cacheable" vengono cachati lato Anthropic per 5 minuti (cache TTL standard) e ogni nuova chiamata che ha lo stesso prefix beneficia del cache-hit. La granularità minima per attivare la cache è 1024 token su Sonnet/Haiku e 2048 token su Opus. La cache è scoped al workspace API key del cliente, isolata fra workspace diversi anche dello stesso account. La fattura distingue tre tipi di token: input_tokens standard ($5/M Opus), cache_creation_input_tokens ($6.25/M Opus, +25% del prezzo standard, costo del primo write in cache), cache_read_input_tokens ($0.50/M Opus, 10% del prezzo standard, lettura da cache). Il break-even per il caching è tipicamente al secondo hit: la prima chiamata paga +25% per scrivere in cache, la seconda al 10% recupera ampiamente il delta della prima.

La verifica del cache-hit è semplice ma quasi nessuno la fa. La response API include automaticamente i tre contatori, e basta loggarli. Sul cliente che ho audited, il loro middleware logger registrava solo usage.input_tokens e usage.output_tokens ignorando i due contatori cache. Il dato di cache-hit non era visibile nel loro dashboard di monitoring. Questo è il primo intervento di setup che propongo in qualunque audit AI: instrumentare il logger per catturare i tre contatori token, aggiungere alla CSV mensile il rapporto cache_read / (cache_read + cache_creation + input). Senza questo dato, ogni discussione su ottimizzazione costi è cieca.

Se vuoi capire dove perdi soldi sulla bolletta API senza saperlo

Nel mio hub dedicato all'AI per aziende, sezione sviluppo raccolgo articoli su come strutturo le pipeline AI di produzione in modo cost-aware. Il prompt caching è la singola leva più potente del listino Anthropic 2026, e il delta fra utilizzo naive e utilizzo ottimale è tipicamente fra il 60% e il 90% della spesa mensile. Vale la pena partire da qui prima di qualunque altra ottimizzazione.

La checklist in nove punti per portare il cache-hit dal 30% al 90%

Punto uno: posiziona system prompt + tool list all'inizio del messaggio e marca cache_control all'ultimo elemento stabile. Il caching funziona sul prefix, non sul suffix. Se metti la richiesta utente prima del system prompt non c'è cache. Se metti il marker cache_control su un elemento che cambia ad ogni chiamata, la cache si invalida ogni volta. Mitigation: ordine canonico in tutti i messaggi: system prompt → tool definitions → conversation history → user message corrente. Marker cache_control sull'ultimo elemento stabile (tipicamente fine tool definitions oppure fine conversation history precedente).

Punto due: stabilizza il system prompt eliminando contenuto dinamico. Pattern che ho visto rovinare il caching: data attuale iniettata nel system prompt ("Today is {date}"), counter incrementale ("Question #{n}"), session ID, user ID nel preambolo. Ognuno di questi cambia il prefix e azzera il cache. Mitigation: spostare i contenuti dinamici dopo il marker cache_control oppure dentro il singolo user message, mantenere il system prompt strict-static.

Punto tre: tool list deve essere ordinata deterministica e non costruita da set Python o JS. I set in Python e gli object literals in JS hanno ordine non garantito. Una pipeline che costruisce la tool list iterando un set produce ordering diverso fra una chiamata e l'altra, e ogni chiamata vede una cache miss. Mitigation: lista esplicita ordinata, oppure sorting deterministico (alphabetic by name) prima della serializzazione.

Punto quattro: ottimizza l'allocazione dei breakpoints cache_control. Anthropic permette fino a 4 cache breakpoint per messaggio. Se la tua conversation è lunga, allocare i 4 breakpoint nei punti giusti (es. fine system prompt, fine tool definitions, fine prima parte conversation history, fine seconda parte) permette caching incrementale che resta hit anche quando la conversation cresce. Mitigation: identificare 2-3 sezioni della conversation che restano stabili oltre il primo turn e marcarle con breakpoint dedicato.

Punto cinque: separa i contenuti specifici-utente in user message, non in system prompt. Pattern errato che vedo spesso: mettere "Sei l'assistente di Marco Rossi, manager del reparto vendite" nel system prompt. Questo costringe a cambiare system prompt per ogni utente e vanifica il caching. Mitigation: user-specific context dentro il primo user message ("Sono Marco Rossi del reparto vendite, ho la seguente richiesta..."), system prompt generico shareable across users.

Punto sei: gestisci correttamente la conversation history per tier. In multi-turn conversation l'history cresce. Se non gestita, ogni turn invalida la cache del prefix che cresce ogni volta. Mitigation: applicare cache_control sul terzo penultimo turn (così che cresce monotonicamente di un turn alla volta dopo il break) e sul fine system+tools (sempre cacheable). I primi turn sono cache hit anche quando la conversation è arrivata al turno 30.

Punto sette: allinea il TTL della cache al pattern di traffico effettivo. Cache TTL standard è 5 minuti. Anthropic offre extended_cache_ttl (1 ora) per use case con traffico irregolare. Pattern che ho visto: agent enterprise interno con utilizzo discontinuo, dove gli utenti tornano dopo 15-30 minuti di pausa. Su 5-min TTL la cache è morta ad ogni nuova sessione, su 1-h TTL il cache-hit si triplica. Mitigation: misurare interval medio fra chiamate dello stesso utente, scegliere TTL accordingly.

Punto otto: stack il caching col batch quando il workload lo permette. Anthropic supporta batch API che addebita -50% sui token, e il batch è cumulativo con il caching: cache-hit in batch costa $0.25/M Opus invece di $0.50/M. Per pipeline con tolleranza a latency (es. job notturni di summarization, generazione contenuti programmati), il pattern stacked batch+cache porta il costo effettivo a 5% del prezzo input standard. Mitigation: identificare i workload tolleranti a latency e migrarli a batch, mantenendo lo stesso prefix structure ottimizzata.

Punto nove: monitora il cache-hit ratio come KPI di pipeline. Senza monitoring continuo, le ottimizzazioni applicate decadono nel tempo (un developer che aggiunge un campo dinamico al system prompt, un product manager che chiede di iniettare la data per audit, un cambio tool che rompe l'ordering). Mitigation: dashboard interno con cache-hit ratio per agent, alert quando scende sotto soglia (tipicamente 70%), revisione settimanale del trend.

I nove punti sopra coprono il 90%+ dei casi che ho incontrato in audit consulenziali nei primi quattro mesi del 2026. Quando il cliente ha applicato anche solo i punti 1, 2, 5 e 6 (i più semplici), ho misurato salti di cache-hit dal 30% al 70-80% in una settimana di lavoro. I punti 3, 4 e 9 portano il salto residuo per arrivare al 90%, ma richiedono riorganizzazione strutturale del codice e setup di monitoring che impegnano 8-12 giornate di engineering. Il pattern di adoption che vedo è quasi sempre lo stesso: punti facili applicati immediatamente con ROI visibile in fattura del mese successivo, punti strutturali pianificati a 30-60 giorni con ROI consolidato sull'anno fiscale.

Tre anti-pattern di codice che rompono la cache senza che tu te ne accorga

Oltre ai nove punti positivi sopra, ci sono tre anti-pattern di codice che ho visto distruggere il cache-hit ratio in modo silenzioso e che vale la pena enumerare specificatamente perché il developer che li scrive raramente sa di starlo facendo.

Anti-pattern uno: JSON.stringify del system prompt costruito da object con ordering non deterministico. In Node.js JSON.stringify({a:1, b:2}) non è garantito per ritornare la stessa stringa di JSON.stringify({b:2, a:1}) in tutte le versioni di V8 (anche se nelle versioni moderne lo è). In Python json.dumps di un dict normale rispetta l'insertion order da Python 3.7, ma json.dumps di un set fa ordering arbitrario. Se costruisci il system prompt da una struttura dati non lista ordinata, ogni rebuild della struttura può produrre stringa diversa e cache miss. Mitigation: convertire sempre a lista ordinata prima della serializzazione, oppure usare json.dumps(..., sort_keys=True).

Anti-pattern due: caching aggressivo lato applicazione che riusa il system prompt pre-compilato ma scarta header API. Alcuni developer per ottimizzare il time-to-first-byte cachano lato applicazione (in Redis, in memory, in CDN edge) il prompt compilato ma poi modificano l'header cache_control o aggiungono un model_id parameter dinamico durante il forwarding. Anthropic vede una request con prefix identica ma altri parametri diversi, e gestisce la cache con la propria logica di hashing che può non essere quello che il developer si aspetta. Mitigation: se cachi lato applicazione, cachare l'intero payload pronto da inviare, non frammenti.

Anti-pattern tre: logging che modifica il payload prima dell'invio. Ho visto pipeline dove un middleware di logging clonava il payload, lo "abbelliva" per il log (es. truncate del system prompt ai primi 500 token per visibilità), e poi inviava il payload originale. Sembra innocuo, ma in alcune implementazioni l'oggetto è stato modificato in place per side effect del clone non profondo, e Anthropic riceveva il payload abbreviato. Cache miss garantito su tutte le request. Mitigation: logging deve sempre operare su deep copy del payload, mai sul payload originale.

Questi tre anti-pattern, presi insieme, rappresentano il 60-70% dei cache miss residui dopo che la checklist dei nove punti è stata applicata. La diagnosi richiede revisione del codice tra layer applicativo e SDK Anthropic, ed è il deliverable di una giornata-uomo per agent della pipeline. Per il consulente che propone audit AI economici, è la fascia di engagement con ROI più rapido nel 2026.

Cosa cambia col tokenizer di Opus 4.7 ad aprile 2026

Una nota di metodo che ho discusso in dettaglio nell'articolo sulla tokenizzazione italiana: ad aprile 2026 Anthropic ha rilasciato Opus 4.7 con un nuovo tokenizer che produce in media il 35% di token in più rispetto alla versione precedente, a parità di prezzo headline. Per chi aveva calibrato il caching su Opus 4.6, l'aggiornamento ha introdotto due effetti collaterali. Primo, la cache scritta su Opus 4.6 è stata invalidata (i token sono diversi), e i primi giorni di traffico sotto Opus 4.7 hanno pagato cache_creation invece che cache_read. Secondo, il calcolo di break-even del caching cambia perché i token complessivi sono il 35% di più, ma il prezzo per token è invariato, quindi il valore assoluto del risparmio sale del 35%. Net-net, dopo Opus 4.7 il caching workspace-level è ancora più conveniente in valore assoluto, ma chi non ha rifatto il dimensionamento del cache_control sul nuovo tokenizer potrebbe avere il prefix marker non più allineato al breakpoint ideale (es. il prefix che era 1024 token su 4.6 è 1382 token su 4.7, e il breakpoint potrebbe essere meglio piazzato 200 token più indietro). Mitigation: revisione del setup caching al primo cambio di modello, sempre.

Il pattern operativo che porto sul tavolo del cliente PMI italiano è "audit cache-hit attuale + applicazione checklist + monitoring continuo + revisione ad ogni model release". Il deliverable misura il delta cost prima/dopo, il cliente vede il risparmio in fattura, il valore consulenziale è cristallino. Per agent enterprise medio-complessi con bolletta API sopra i 1.000 dollari/mese, il ROI di un engagement di una settimana è tipicamente 6-12 mesi di savings, e il pattern continua a generare valore mentre la pipeline cresce. Se vuoi un audit del cache-hit attuale della tua pipeline AI, il modulo di preventivo gratuito è il punto da cui inquadrare la richiesta in due minuti, sette domande, prima della prossima fattura.