Utilisation d'outils avec la mise en cache des prompts

Cette page couvre la « prompt caching » (mise en cache des prompts) pour les définitions d'outils : où placer les points de rupture cache_control, comment defer_loading préserve votre cache, et ce qui l'invalide. Pour la mise en cache des prompts en général, consultez Mise en cache des prompts.



cache_control sur les définitions d'outils

Placez cache_control: {"type": "ephemeral"} sur le dernier outil de votre tableau tools. Cela met en cache l'intégralité du préfixe des définitions d'outils, du premier outil jusqu'au point de rupture marqué :

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": {
          "timezone": { "type": "string" }
        },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ]
}

Pour mcp_toolset, le point de rupture cache_control se place sur le dernier outil de l'ensemble. Vous ne contrôlez pas l'ordre des outils au sein d'un ensemble d'outils MCP, placez donc le point de rupture sur l'entrée mcp_toolset elle-même et l'API l'applique au dernier outil développé.



defer_loading et préservation du cache

Les outils différés ne sont pas inclus dans le préfixe de l'invite système. Lorsque le modèle découvre un outil différé via la recherche d'outils, la définition est ajoutée en ligne sous forme de bloc tool_reference dans l'historique de la conversation. Le préfixe n'est pas modifié, donc la mise en cache des prompts est préservée.

Cela signifie que l'ajout dynamique d'outils via la recherche d'outils ne casse pas votre cache. Vous pouvez démarrer une conversation avec un petit ensemble d'outils toujours chargés (mis en cache), laisser le modèle découvrir des outils supplémentaires selon les besoins, et conserver le même succès de cache à chaque tour.

defer_loading agit également indépendamment de la construction de la grammaire pour le mode strict. La grammaire se construit à partir de l'ensemble complet des outils, quels que soient les outils différés, de sorte que la mise en cache des prompts et la mise en cache de la grammaire sont toutes deux préservées lorsque les outils se chargent dynamiquement.



Ce qui invalide votre cache

Le cache suit une hiérarchie de préfixes (tools → system → messages), donc un changement à un niveau invalide ce niveau et tout ce qui suit :



Les résultats des outils serveur sont mis en cache automatiquement

Lorsque votre requête a la mise en cache des prompts activée et que Claude utilise un outil serveur tel que la recherche web, la récupération web ou l'exécution de code, l'API place automatiquement un point de rupture de cache sur le résultat de l'outil serveur avant d'exécuter l'itération suivante de la boucle agentique. Cela permet aux itérations ultérieures au sein de la même requête de lire le préfixe croissant depuis le cache au lieu de le retraiter.

Ce point de rupture automatique utilise toujours le TTL par défaut de 5 minutes, indépendamment de tout TTL que vous définissez sur vos propres marqueurs cache_control. Dans la réponse usage, ces écritures apparaissent sous cache_creation.ephemeral_5m_input_tokens, vous pouvez donc voir des écritures de cache de 5 minutes même lorsque chaque cache_control que vous définissez utilise un TTL d'une heure.

Ce comportement ne s'applique que lorsque votre requête comporte déjà au moins un marqueur cache_control. Les requêtes sans mise en cache des prompts ne reçoivent pas le point de rupture automatique.



Tableau d'interaction par outil



Prochaines étapes