AP30 · Préfixe instable qui casse le cache

Définition

Le début du contexte change d’un appel à l’autre : horodatage à la seconde dans le prompt système, JSON sérialisé sans ordre de clés stable, outils ajoutés, retirés ou réordonnés, modèle changé en cours de session. Le cache de préfixe est perdu à chaque tour.

Symptômes observables

• Le taux de succès du cache, lu dans l’usage de l’API ou dans `gen_ai.usage.cache_read.input_tokens`, reste proche de zéro.
• Le coût par tour ne décroît pas au fil de la session, et `cache_creation_input_tokens` reste élevé à chaque appel.
• L’empreinte du prompt système change d’un appel à l’autre dans une même session.
• La latence du premier token ne baisse pas au fil de la session.

Pourquoi c'est nuisible

Le cache ne sert que si le préfixe est identique à l’octet près : un seul token modifié au début invalide tout ce qui suit. Or, dans un agent, le contexte relu pèse bien plus que la sortie produite, environ 100 pour 1 chez Manus.

Un choix défendable quand…

• Un appel isolé, sans session ni contexte relu, où le cache n’a rien à réutiliser.

Chiffres

• Sur Claude Sonnet, Manus cite 0,30 $ par million de tokens servis par le cache contre 3 $ sans cache, soit un écart de 10 fois.
• L’équipe Claude Code d’Anthropic surveille le taux de succès du cache par des alertes et déclare un incident de gravité quand il est trop bas (avril 2026).

Remèdes du catalogue

• D1 · Compaction — Une compaction compatible avec le cache : même prompt système, mêmes outils, seul l’historique est résumé.
• D5 · Sous-agent d’isolation de contexte — Pour changer de modèle, un sous-agent prépare un message de passation au lieu de basculer dans la même conversation.
• A2 · Outils et interface agent-machine (ACI) — Masquer les outils indisponibles plutôt que les retirer, pour que leurs définitions restent identiques d’un appel à l’autre.

Mesures hors catalogue

• Un contexte en ajout seul, une sérialisation déterministe et les informations variables, comme l’heure, en fin de contexte.
• Une alerte sur le taux de succès du cache, traité comme une métrique de production.

Patterns détournés

• C1 · Boucle agentique (ReAct)
• D1 · Compaction
• D6 · Harnais longue durée
• F3 · Cascade et routage de modèles

Anti-patterns voisins

• AP25 · Contexte qui gonfle sans gestion

Sources

• Context Engineering for AI Agents: Lessons from Building Manus — Manus (Yichao Ji), 2025-07-18
• Lessons from building Claude Code: Prompt caching is everything — Thariq Shihipar (Anthropic), 2026-04-30