Utilisation d'outils avec la mise en cache des prompts

Cette page traite de la mise en cache des prompts pour les définitions d'outils : où placer les points d'arrêt 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 d'arrêt 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 d'arrêt 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, donc placez le point d'arrêt 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 conversation. Le préfixe reste intact, 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 est construite à partir de l'ensemble complet d'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 une modification à 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 d'arrêt 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 d'arrêt automatique utilise toujours le « TTL » (durée de vie) par défaut de 5 minutes, indépendamment de tout TTL que vous définissez sur vos propres marqueurs cache_control. Dans le champ usage de la réponse, 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 s'applique uniquement 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 d'arrêt automatique.



Tableau des interactions par outil



Étapes suivantes