Prompt caching Anthropic : ce qu'on gagne vraiment en prod

J’ouvrais ma facture Anthropic d’avril : multipliée par 3 par rapport à mars. Pas un drame — l’usage avait monté, c’est cohérent. Mais en regardant de près, 60 % de ce coût était évitable. La cause : un system prompt de 8 000 tokens rejoué à chaque appel d’agent, sans cache. Trois changements dans le payload, et la facture du mois suivant est descendue de 40 %.

Le prompt caching Anthropic est sorti il y a presque deux ans. Pourtant, je continue à voir des intégrations en prod où il n’est pas activé — soit par méconnaissance, soit parce que le bénéfice est mal compris. Voici ce que j’ai retenu après l’avoir branché sur 6-7 projets clients.

Comment ça marche, en 30 secondes

Tu marques certains segments de ton prompt avec un attribut cache_control: { type: "ephemeral" }. Anthropic stocke ces segments dans un cache éphémère côté serveur. Au prochain appel, si les tokens précédant le cache_control sont identiques au token près, ils sont relus depuis le cache au lieu d’être retraités.

Coût : +25 % par rapport à l’input normal au premier write. 10 % de l’input normal en read cache. TTL par défaut 5 minutes (rallongé en option à 1 heure). Minimum cacheable : 1 024 tokens sur Sonnet/Opus, 2 048 sur Haiku.

Le calcul mental est simple : si tu rejoues un même segment de 5 000 tokens 4 fois en 5 minutes, tu paies 1.25 + 0.10 × 3 = 1.55 fois le coût normal au lieu de 4. Soit -61 %.

Quand ça vaut le coup

• System prompt long et stable (> 2 000 tokens) : tone of voice, instructions de tâche, exemples few-shot. Cas le plus rentable.
• Définitions d’outils dans un agent : 10-20 tools = 3 000-8 000 tokens de schéma JSON, identiques à chaque tour de boucle. Énorme gain.
• Contexte RAG fixe : documents légaux, CGU, politique d’entreprise. Si tu passes les mêmes 50 chunks à chaque requête utilisateur, cache.
• Workflows d’agents itératifs : une boucle de 10 tool calls qui réutilise le même bagage = 9 cache reads à 10 %.

Quand ça ne sert à rien (voire coûte plus cher)

• Sessions courtes : un seul appel par utilisateur, pas de réutilisation. Tu paies juste le surcoût du write (+25 %) sans jamais lire.
• Prompts < 1 024 tokens : sous le seuil, le cache_control est silencieusement ignoré. L’API ne te prévient pas.
• Prompt dynamique au début : si la moindre variable change avant la zone marquée cache_control, tout le préfixe est invalidé. Place tes segments dynamiques après les segments cachés, jamais avant.
• TTL dépassé : au-delà de 5 minutes sans appel, cache flushé. Pas grave si l’utilisateur revient — mais ça ruine le calcul si ton trafic est sporadique.

Le pattern qui marche

Quatre segments, dans cet ordre :

1. System rule (rarement modifiée) → cache_control
2. Tool definitions (changent à chaque release) → cache_control
3. Contexte fixe (RAG, profil utilisateur, données de session) → cache_control si > 1 024 tokens
4. User turn (varie à chaque appel) → pas de cache_control

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: [
    { type: "text", text: SYSTEM_RULE, cache_control: { type: "ephemeral" } },
    { type: "text", text: TOOL_INSTRUCTIONS, cache_control: { type: "ephemeral" } },
    { type: "text", text: USER_PROFILE, cache_control: { type: "ephemeral" } },
  ],
  tools: TOOLS,
  messages: [{ role: "user", content: userInput }],
});

console.log(response.usage);
// cache_creation_input_tokens vs cache_read_input_tokens

Le champ usage.cache_read_input_tokens est ton ami. Si tu ne le surveilles pas, tu ne sauras pas si le cache hit ou pas. J’ai vu trois projets où le cache était activé mais jamais utilisé — un caractère de différence dans le system prompt à chaque appel (timestamp, UUID), invalidation systématique.

Les pièges en prod

• Debug invisible : un cache miss ne lève aucune erreur. Tu vois juste la facture monter. Logue cache_read_input_tokens à chaque appel et alerte si le ratio descend.
• Mesure du hit rate : avant d’activer, capture une journée d’appels en prod. Compte combien de prompts auraient pu être réutilisés. Si < 30 %, le caching te coûte plus qu’il ne rapporte.
• Releases qui invalident tout : à chaque déploiement modifiant le system prompt, tu repaies un write complet pour chaque utilisateur actif. Sur un service avec 10k utilisateurs simultanés, ça pique. Releases atomiques recommandées hors heures de pointe.
• Multi-tenancy : si chaque tenant a un system prompt légèrement différent, tu te retrouves avec N caches séparés. Réfléchis à factoriser le tronc commun en cache_control et à mettre la partie tenant-specific après.

Quand ne PAS l’utiliser

Si tu fais < 100 appels par jour, ne perds pas de temps avec le caching. La complexité n’en vaut pas la peine, et le surcoût du premier write n’est jamais amorti. Active-le quand tu vois ton agent boucler et que le même bagage repasse 5 fois — pas avant.

Pour le reste, c’est probablement le levier d’optimisation avec le meilleur ratio effort/gain sur une app LLM en prod.