Utilisation d'outils avec la mise en cache des prompts

Cette page traite de la « prompt caching » (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 ; placez donc le point d'arrêt sur l'entrée mcp_toolset elle-même, et l'API l'applique au dernier outil développé.

Les entrées d'ensembles d'outils computer use (utilisation de l'ordinateur) et browser use (utilisation du navigateur) suivent la même règle : placez cache_control sur l'entrée de l'ensemble d'outils elle-même, et le point d'arrêt se place après la définition de l'ensemble d'outils. Il n'est pas accepté à l'intérieur de l'entrée configs d'un membre, car les membres de l'ensemble d'outils se chargent comme une seule définition. Au sein d'une action par lot, un marqueur cache_control sur n'importe lequel des blocs tool_use ou tool_result membres du tour est accepté et prend effet à la fin de ce lot, de sorte que plusieurs marqueurs dans un même lot agissent comme un seul point d'arrêt. Chaque marqueur compte toujours dans la limite de quatre points d'arrêt par requête ; utilisez-en donc un par tour.



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 reste intact, de sorte que 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 accès au 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 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), de sorte qu'une modification à un niveau invalide ce niveau et tout ce qui le suit :



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

Lorsque la mise en cache des prompts est activée pour votre requête 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 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 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 d'arrêt automatique.



Tableau des interactions par outil



Étapes suivantes