On dit souvent en ingénierie que « Cache Rules Everything Around Me », et la même règle s'applique aux agents.
Les produits agents à longue durée de vie comme Claude Code sont rendus possibles grâce au prompt caching qui nous permet de réutiliser les calculs des allers-retours précédents et de réduire considérablement la latence et le coût.
Qu'est-ce que le prompt caching, comment fonctionne-t-il et comment l'implémenter techniquement ? En savoir plus dans l'article de @RLanceMartin sur le prompt caching et notre nouveau lancement d'auto-caching.
Chez Claude Code, nous construisons toute notre infrastructure autour du prompt caching. Un taux de succès élevé du cache réduit les coûts et nous permet de créer des limites de débit plus généreuses pour nos offres d'abonnement, donc nous configurons des alertes sur notre taux de succès du cache et déclarons des SEVs s'il est trop bas.
Voici les leçons (souvent contre-intuitives) que nous avons apprises en optimisant le prompt caching à grande échelle.
Organisez votre prompt pour le caching
Le prompt caching fonctionne par correspondance de préfixe — l'API met en cache tout depuis le début de la requête jusqu'à chaque point de rupture cache_control. Cela signifie que l'ordre dans lequel vous placez les éléments est extrêmement important, vous voulez que le plus possible de vos requêtes partagent un préfixe commun.
La meilleure façon de procéder est de mettre le contenu statique en premier, le contenu dynamique en dernier. Pour Claude Code, cela ressemble à :
- Prompt système statique & Outils (mis en cache globalement)
- Claude.MD (mis en cache dans un projet)
- Contexte de session (mis en cache dans une session)
- Messages de conversation
De cette façon, nous maximisons le nombre de sessions qui partagent des hits de cache.
Mais cela peut être étonnamment fragile ! Des exemples de raisons pour lesquelles nous avons déjà cassé cet ordre incluent : mettre un horodatage détaillé dans le prompt système statique, mélanger les définitions d'ordre des outils de manière non déterministe, mettre à jour les paramètres des outils (par exemple, quels agents l'AgentTool peut appeler), etc.
Utilisez les messages pour les mises à jour
Il peut arriver que les informations que vous mettez dans votre prompt deviennent obsolètes, par exemple si vous avez l'heure ou si l'utilisateur modifie un fichier. Il peut être tentant de mettre à jour le prompt, mais cela entraînerait un cache miss et pourrait finir par coûter cher à l'utilisateur.
Envisagez plutôt de passer ces informations via les messages lors du tour suivant. Dans Claude Code, nous ajoutons une balise <system-reminder> dans le prochain message utilisateur ou résultat d'outil avec les informations mises à jour pour le modèle (par exemple, nous sommes maintenant mercredi), ce qui aide à préserver le cache.
Ne changez pas de modèle en cours de session
Les caches de prompt sont propres à chaque modèle et cela peut rendre le calcul du prompt caching assez contre-intuitif.
Si vous êtes à 100 000 tokens dans une conversation avec Opus et que vous voulez poser une question assez facile à répondre, il serait en réalité plus coûteux de passer à Haiku que de laisser Opus répondre, car nous devrions reconstruire le cache de prompt pour Haiku.
Si vous devez changer de modèle, la meilleure façon de le faire est d'utiliser des sous-agents, où Opus préparerait un message de « passage » à un autre modèle sur la tâche à accomplir. Nous faisons cela souvent avec les agents Explore dans Claude Code qui utilisent Haiku.
N'ajoutez ni ne supprimez jamais d'outils en cours de session
Modifier l'ensemble d'outils en milieu de conversation est l'une des façons les plus courantes de casser le prompt caching. Cela semble intuitif — vous ne devriez donner au modèle que les outils dont vous pensez qu'il a besoin maintenant. Mais comme les outils font partie du préfixe mis en cache, ajouter ou supprimer un outil invalide le cache pour toute la conversation.
Mode Plan — Conçu autour du cache
Le mode Plan est un excellent exemple de conception de fonctionnalités autour des contraintes de caching. L'approche intuitive serait : lorsque l'utilisateur entre en mode plan, échanger l'ensemble des outils pour n'inclure que les outils en lecture seule. Mais cela casserait le cache.
Au lieu de cela, nous gardons tous les outils dans la requête en permanence et utilisons EnterPlanMode et ExitPlanMode comme outils eux-mêmes. Lorsque l'utilisateur active le mode plan, l'agent reçoit un message système expliquant qu'il est en mode plan et quelles sont les instructions — explorer la base de code, ne pas modifier les fichiers, appeler ExitPlanMode lorsque le plan est terminé. Les définitions d'outils ne changent jamais.
Cela a un avantage supplémentaire : comme EnterPlanMode est un outil que le modèle peut appeler lui-même, il peut entrer en mode plan de manière autonome lorsqu'il détecte un problème difficile, sans casser le cache.
Recherche d'outils — Différer au lieu de supprimer
Le même principe s'applique à notre fonctionnalité de recherche d'outils. Claude Code peut avoir des dizaines d'outils MCP chargés, et les inclure tous dans chaque requête serait coûteux. Mais les supprimer en cours de conversation casserait le cache.
Notre solution : defer_loading. Au lieu de supprimer les outils, nous envoyons des stubs légers — juste le nom de l'outil, avec defer_loading: true — que le modèle peut « découvrir » via un outil ToolSearch quand nécessaire. Les schémas complets des outils ne sont chargés que lorsque le modèle les sélectionne. Cela maintient le préfixe mis en cache stable : les mêmes stubs sont toujours présents dans le même ordre.
Heureusement, vous pouvez utiliser l'outil recherche d'outils via notre API pour simplifier cela.
Contexte de bifurcation — Compaction
La compaction est ce qui se produit lorsque vous manquez d'espace dans la fenêtre de contexte. Nous résumons la conversation jusqu'à présent et continuons une nouvelle session avec ce résumé.
Étonnamment, la compaction présente de nombreux cas limites avec le prompt caching qui peuvent être contre-intuitifs.
En particulier, lorsque nous compactons, nous devons envoyer toute la conversation au modèle pour générer un résumé. S'il s'agit d'un appel API distinct avec un prompt système différent et aucun outil (ce qui est l'implémentation simple), le préfixe mis en cache de la conversation principale ne correspond pas du tout. Vous payez le plein prix pour tous ces tokens d'entrée, augmentant considérablement le coût pour l'utilisateur.
La solution — Bifurcation sans risque de cache
Lorsque nous exécutons la compaction, nous utilisons exactement le même prompt système, contexte utilisateur, contexte système et définitions d'outils que la conversation parente. Nous ajoutons les messages de la conversation parente en préfixe, puis nous ajoutons le prompt de compaction comme nouveau message utilisateur à la fin.
Du point de vue de l'API, cette requête est presque identique à la dernière requête du parent — même préfixe, mêmes outils, même historique — donc le préfixe mis en cache est réutilisé. Les seuls nouveaux tokens sont le prompt de compaction lui-même.
Cela signifie cependant que nous devons sauvegarder un « tampon de compaction » pour avoir suffisamment d'espace dans la fenêtre de contexte pour inclure le message compact et les tokens de sortie du résumé.
La compaction est délicate mais heureusement, vous n'avez pas besoin d'apprendre ces leçons vous-même — sur la base de nos apprentissages de Claude Code, nous avons intégré la compaction directement dans l'API, afin que vous puissiez appliquer ces modèles dans vos propres applications.
Leçons apprises
- Le prompt caching est une correspondance de préfixe. Tout changement n'importe où dans le préfixe invalide tout ce qui le suit. Concevez l'ensemble de votre système autour de cette contrainte. Obtenez le bon ordre et la plupart du caching fonctionne gratuitement.
- Utilisez les messages au lieu de modifier le prompt système. Vous pourriez être tenté de modifier le prompt système pour faire des choses comme entrer en mode plan, changer la date, etc., mais il serait en fait préférable d'insérer ces éléments dans les messages pendant la conversation.
- Ne changez pas d'outils ou de modèle en cours de conversation. Utilisez les outils pour modéliser les transitions d'état (comme le mode plan) plutôt que de modifier l'ensemble des outils. Différez le chargement des outils au lieu de les supprimer.
- Surveillez votre taux de succès du cache comme vous surveillez la disponibilité. Nous alertons sur les ruptures de cache et les traitons comme des incidents. Quelques points de pourcentage de taux d'échec du cache peuvent affecter considérablement le coût et la latence.
- Les opérations de bifurcation doivent partager le préfixe du parent. Si vous devez exécuter un calcul secondaire (compaction, résumé, exécution de compétence), utilisez des paramètres identiques et sans risque de cache pour obtenir des hits de cache sur le préfixe du parent.
Claude Code est construit autour du prompt caching dès le premier jour, vous devriez faire de même si vous construisez un agent.
