Tool-Nutzung mit Prompt-Caching

Diese Seite behandelt „prompt caching“ (Prompt-Caching) für Tool-Definitionen: wo du cache_control-Breakpoints platzierst, wie defer_loading deinen Cache erhält und was ihn invalidiert. Für allgemeines Prompt-Caching siehe Prompt-Caching.

cache_control auf Tool-Definitionen

Platziere cache_control: {"type": "ephemeral"} auf dem letzten Tool in deinem tools-Array. Dadurch wird das gesamte Präfix der Tool-Definitionen gecacht, vom ersten Tool bis zum markierten Breakpoint:

{
  "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" }
    }
  ]
}

Bei mcp_toolset landet der cache_control-Breakpoint auf dem letzten Tool im Set. Du kontrollierst die Tool-Reihenfolge innerhalb eines MCP-Toolsets nicht, platziere den Breakpoint daher auf dem mcp_toolset-Eintrag selbst, und die API wendet ihn auf das letzte expandierte Tool an.

Die Toolset-Einträge für Computer Use und Browser Use folgen derselben Regel: Platziere cache_control auf dem Toolset-Eintrag selbst, und der Breakpoint landet nach der Definition des Toolsets. Innerhalb des configs-Eintrags eines Mitglieds wird es nicht akzeptiert, da die Mitglieder des Toolsets als eine einzige Definition geladen werden. Innerhalb einer Batch-Aktion wird ein cache_control-Marker auf einem beliebigen der tool_use- oder tool_result-Blöcke der Mitglieder des Turns akzeptiert und wirkt am Ende dieses Batches, sodass mehrere Marker in einem Batch als ein einziger Breakpoint fungieren. Jeder Marker zählt dennoch zum Limit der Anfrage von vier Breakpoints, verwende also einen pro Turn.

defer_loading und Cache-Erhaltung

Verzögert geladene Tools sind nicht im System-Prompt-Präfix enthalten. Wenn das Modell ein verzögert geladenes Tool über die Tool-Suche entdeckt, wird die Definition inline als tool_reference-Block an den Gesprächsverlauf angehängt. Das Präfix bleibt unberührt, sodass das Prompt-Caching erhalten bleibt.

Das bedeutet, dass das dynamische Hinzufügen von Tools über die Tool-Suche deinen Cache nicht bricht. Du kannst ein Gespräch mit einem kleinen Satz immer geladener Tools (gecacht) beginnen, das Modell bei Bedarf zusätzliche Tools entdecken lassen und über jeden Turn hinweg denselben Cache-Treffer beibehalten.

defer_loading wirkt außerdem unabhängig von der Grammatikkonstruktion für den Strict Mode. Die Grammatik wird aus dem vollständigen Toolset aufgebaut, unabhängig davon, welche Tools verzögert geladen werden, sodass sowohl Prompt-Caching als auch Grammatik-Caching erhalten bleiben, wenn Tools dynamisch geladen werden.

Was deinen Cache invalidiert

Der Cache folgt einer Präfix-Hierarchie (tools → system → messages), sodass eine Änderung auf einer Ebene diese Ebene und alles danach invalidiert:

Server-Tool-Ergebnisse werden automatisch gecacht

Wenn in deiner Anfrage Prompt-Caching aktiviert ist und Claude ein Server-Tool wie Websuche, Web-Fetch oder Code-Ausführung verwendet, platziert die API automatisch einen Cache-Breakpoint auf dem Server-Tool-Ergebnis, bevor die nächste Iteration der agentischen Schleife ausgeführt wird. Dadurch können spätere Iterationen innerhalb derselben Anfrage das wachsende Präfix aus dem Cache lesen, anstatt es erneut zu verarbeiten.

Dieser automatische Breakpoint verwendet immer die Standard-TTL von 5 Minuten, unabhängig von jeder TTL, die du auf deinen eigenen cache_control-Markern setzt. In der usage der Antwort erscheinen diese Schreibvorgänge unter cache_creation.ephemeral_5m_input_tokens, sodass du möglicherweise 5-Minuten-Cache-Schreibvorgänge siehst, selbst wenn jedes von dir gesetzte cache_control eine TTL von 1 Stunde verwendet.

Dieses Verhalten gilt nur, wenn deine Anfrage bereits mindestens einen cache_control-Marker enthält. Anfragen ohne Prompt-Caching erhalten den automatischen Breakpoint nicht.

Interaktionstabelle pro Tool

Nächste Schritte