Claude API Prompt Caching: Wann es Geld spart und wann nicht
Ich betreibe einen Agent, der bei jedem Turn eine Knowledge Base mit 15.000 Tokens liest. Mehrstufige Konversation, rund 40 Aufrufe pro Nutzer-Session. Ohne Caching zahlt jeder Turn erneut die vollen Input-Token-Kosten für ein Context Window, das sich nie ändert. Mit Claude API Prompt Caching wird die Knowledge Base einmal zum 1,25-fachen Input-Preis geschrieben, jeder weitere Read kostet dann das 0,1-fache. Nach dem zweiten Aufruf ist es bereits günstiger als die volle Input-Rate. Genau dafür existiert dieses Feature.
Nutzen Sie Prompt Caching, wenn Sie einen grossen, stabilen Prefix haben, der sich über Aufrufe wiederholt: RAG-Pipelines, mehrstufige Agents mit festen System-Prompts, tool-lastige Workflows, in denen allein die Tool-Definitionen tausende Tokens umfassen. Verzichten Sie darauf bei einzelnen Prompts, kalten Aufrufen mit mehr als fünf Minuten Abstand oder Prompts unter 1.024 Tokens bei Sonnet (2.048 bei Haiku). Der Break-even liegt bei etwa zwei Treffern innerhalb des TTL-Fensters. Darunter frisst der 25%-Write-Aufschlag Ihre Ersparnisse auf.
Wie Claude Caching implementiert
Anthropic stellt Caching über ein cache_control-Feld an einzelnen Content-Blöcken bereit. Sie markieren einen Block als cachebar mit {"type": "ephemeral"} und die API hasht diesen Block plus alles, was im Prompt davor steht. Beim nächsten Aufruf, wenn der Hash einem Eintrag innerhalb der 5-Minuten-TTL entspricht, zahlen Sie Cache-Read-Raten statt voller Input-Raten.
Zwei Details sind wichtig. Erstens ist der Cache-Key der vollständige Prefix bis einschliesslich des markierten Blocks, nicht nur der Block selbst. Ändern Sie ein einziges Zeichen weiter vorn im System-Prompt, greift der Cache nicht. Zweitens ist das 5-Minuten-Fenster eine gleitende TTL: jeder Treffer erneuert sie. Ein aktiver Agent, der eine gecachte Knowledge Base im Umlauf hält, bewahrt diesen Cache unbegrenzt warm, ein ruhiger Agent verliert ihn zwischen Nutzer-Sessions.
Cache-Breakpoints lassen sich auf bis zu vier Blöcken pro Request setzen. Das übliche Muster: ein Breakpoint am System-Prompt und einer an den Tool-Definitionen, sodass die Tools unabhängig cachen, wenn sich der System-Prompt ändert, die Tools aber gleich bleiben.
Welche Blöcke cachebar sind
Drei Blocktypen akzeptieren cache_control:
- System-Prompt-Blöcke. Das häufigste Ziel. Lange Anweisungen, Persona-Definitionen, Style Guides.
- Tool-Definitionen: das
tools-Array. Bei 20 Tools mit detaillierten JSON-Schemas können allein diese 3.000 bis 5.000 Tokens ausmachen. - Nachrichten-Content-Blöcke, sowohl user als auch assistant. Nützlich für RAG-Muster, in denen Sie abgerufene Dokumente in den User-Turn einfügen.
Der Haken am Message-Level-Caching: Es hilft nur, wenn derselbe Dokumentenblock in nachfolgenden Requests an derselben Position erscheint. Bei den meisten RAG-Pipelines variieren die abgerufenen Chunks pro Query, also zahlt sich Message-Caching selten aus. Die echten Ersparnisse liegen beim System- und Tool-Caching.
Mindest-Token-Zahlen, damit ein Block cache-fähig wird:
- Claude Sonnet 4.6: 1.024 Tokens
- Claude Haiku 4.5: 2.048 Tokens
- Claude Opus 4.7: 1.024 Tokens
Blöcke unterhalb des Minimums werden stillschweigend ignoriert (das cache_control-Feld wird akzeptiert, kein Fehler, aber nichts wird gecacht). Verifizieren Sie es immer über einen Usage-Check, siehe unten.
Die Preisrechnung
Zwei Raten sind relevant:
- Cache Write: 1,25-fach des Basis-Input-Preises (25% Aufschlag auf den ersten Aufruf, der den Eintrag erzeugt)
- Cache Read: 0,1-fach des Basis-Input-Preises (90% Rabatt auf jeden Treffer)
Der Basis-Input für Sonnet 4.6 liegt zum Zeitpunkt dieses Textes bei 3 $ pro Million Tokens. Gecachte Reads landen also bei 0,30 $ pro Million. Writes kosten 3,75 $ pro Million.
Der Break-even ist simpel. Bei einem gecachten Prefix von N Tokens:
- Erster Aufruf: N * 1,25 (Write)
- Jeder weitere Treffer: N * 0,1 (Read)
- Ohne Caching, jeder Aufruf: N * 1,0
Nach einem Treffer haben Sie 1,25N + 0,1N = 1,35N für zwei Aufrufe gezahlt, gegenüber 2,0N ohne Caching. Bereits im Vorteil. Nach zehn Treffern: 1,25N + 1,0N = 2,25N gegenüber 10,0N. Je grösser der Prefix und je mehr Treffer, desto stärker summiert sich der Rabatt.
TypeScript-Beispiel
Hier das Muster, das ich nutze: grosser System-Prompt gecacht, die Request-spezifische User-Nachricht ungecacht.
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const SYSTEM_PROMPT = `You are a customer support agent for a SaaS product.
[... 2,500 tokens of product documentation, tone guide,
policies, escalation rules, FAQ content ...]
`;
async function answerQuestion(userMessage: string) {
const response = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 1024,
system: [
{
type: "text",
text: SYSTEM_PROMPT,
cache_control: { type: "ephemeral" },
},
],
messages: [
{
role: "user",
content: userMessage,
},
],
});
const usage = response.usage;
console.log({
cache_creation_input_tokens: usage.cache_creation_input_tokens,
cache_read_input_tokens: usage.cache_read_input_tokens,
input_tokens: usage.input_tokens,
output_tokens: usage.output_tokens,
});
return response.content;
}
// First call: cache_creation_input_tokens ~= 2500, cache_read_input_tokens = 0
await answerQuestion("How do I reset my password?");
// Second call within 5 minutes: cache_creation = 0, cache_read_input_tokens ~= 2500
await answerQuestion("Can I export my data as CSV?");
Beachten Sie, dass das system-Feld ein Array von Content-Blöcken erwartet, keinen reinen String, sobald Sie cache_control anwenden möchten. Die API akzeptiert auch einen String für den nicht-gecachten Fall, weshalb die meisten Einsteiger-Snippets diese Kurzform verwenden.
Für Prompt Caching innerhalb eines Tool-Use-Workflows gilt dasselbe Muster auch für den Claude API Tool Use-Flow: Tool-Definitionen einmal cachen und über Turns hinweg wiederverwenden.
Cache-Treffer verifizieren
Das usage-Objekt jeder Antwort sagt Ihnen genau, was passiert ist:
input_tokens: ungecachte Input-Tokens zum Standardpreiscache_creation_input_tokens: Tokens, die bei diesem Aufruf in den Cache geschrieben wurden (1,25-facher Preis)cache_read_input_tokens: Tokens, die bei diesem Aufruf aus dem Cache gelesen wurden (0,1-facher Preis)output_tokens: Standard-Output-Rate
Wenn cache_read_input_tokens null ist, obwohl Sie einen Treffer erwartet hätten, hat etwas den Cache invalidiert. Häufige Ursachen: die 5-Minuten-TTL ist abgelaufen, ein Whitespace- oder Zeichenwechsel im gecachten Prefix, oder der Prefix liegt unter der Mindest-Token-Zahl.
Ein schneller Sanity-Check: Loggen Sie das Usage-Objekt bei jedem Produktionsaufruf und alarmieren Sie, wenn die Cache-Trefferquote unter einen erwarteten Schwellwert fällt. Ich führe diese Prüfung im gleichen Muster zur Validierung strukturierter Ausgaben durch, das ich für Claude API Structured Output nutze, da beide dem Prinzip “trust but verify” bei Anthropic-Antworten folgen.
Praxisszenario: Agent mit 15k-Token-Knowledge-Base
Zurück zum Eingangsszenario. Angenommen, ein Agent beantwortet Fragen gegen eine 15.000-Token-Knowledge-Base, die in den System-Prompt geladen ist. Jeder User-Turn umfasst etwa 200 Input-Tokens plus 500 Output-Tokens. Sonnet-4.6-Raten: 3 $ Input, 15 $ Output pro Million.
Ohne Caching, pro Aufruf:
- Input: 15.200 Tokens * 3 $/M = 0,0456 $
- Output: 500 * 15 $/M = 0,0075 $
- Gesamt: 0,0531 $
Mit Caching, erster Aufruf (Cache Write):
- Cache Write: 15.000 * 3,75 $/M = 0,0563 $
- Ungecachter Input: 200 * 3 $/M = 0,0006 $
- Output: 0,0075 $
- Gesamt: 0,0644 $
Mit Caching, nachfolgende Aufrufe (Cache Hit):
- Cache Read: 15.000 * 0,30 $/M = 0,0045 $
- Ungecachter Input: 200 * 3 $/M = 0,0006 $
- Output: 0,0075 $
- Gesamt: 0,0126 $
Vergleichen Sie die Gesamtkosten bei verschiedenen Session-Längen (Aufrufe pro Session, unter der Annahme, dass alle innerhalb des 5-Minuten-Fensters landen):
- 1 Aufruf: ohne Caching 0,053 $, mit Caching 0,064 $, Ersparnis: schlechter
- 2 Aufrufe: ohne Caching 0,106 $, mit Caching 0,077 $, Ersparnis: 27%
- 5 Aufrufe: ohne Caching 0,266 $, mit Caching 0,114 $, Ersparnis: 57%
- 10 Aufrufe: ohne Caching 0,531 $, mit Caching 0,177 $, Ersparnis: 67%
- 40 Aufrufe: ohne Caching 2,124 $, mit Caching 0,554 $, Ersparnis: 74%
Einzelaufrufe verlieren Geld. Zwei Treffer erreichen den Break-even. Alles ab fünf Treffern ist ein klarer Gewinn. Bei einer 40-Turn-Agent-Session reduziert Caching die Rechnung um rund drei Viertel. So verläuft die Kurve, und sie gilt für jede Prefix-Grösse, sobald Sie das Minimum überschreiten.
Fallstricke, an denen Praktiker scheitern
Whitespace-Sensitivität. Der Cache-Key hasht den exakten Byte-Inhalt. Ein abschliessendes Newline durch Ihre Template-Engine, ein Leerzeichen nach einer Variableninterpolation, eine andere Einrücktiefe in einem mehrzeiligen Prompt. All das führt zum Cache-Miss. Bauen Sie Ihren System-Prompt bei jedem Aufruf auf dieselbe Weise, idealerweise durch Laden aus einer einzigen kanonischen Quelle.
Tool-Definitionen invalidieren alles Nachfolgende. Wenn Sie sowohl Tools als auch System-Prompt cachen und eine einzige Tool-Beschreibung ändern, ändert sich der Hash des Tools-Blocks, und jeder nachfolgende Block in der Prefix-Reihenfolge (einschliesslich System-Prompt, falls dieser später kommt) greift ebenfalls nicht. Ordnen Sie Ihre cachebaren Blöcke vom stabilsten zum volatilsten. Tools zuerst, wenn sie selten wechseln, danach System-Prompt, dann alles Dynamischere.
Caching innerhalb einer Nachricht vs. über Nachrichten hinweg. Caching erfolgt über API-Aufrufe hinweg, nicht innerhalb eines einzelnen Aufrufs. Sie können einen Block nicht cachen und im selben Request wiederverwenden. Jeder Request wird unabhängig gegen den Cache geprüft.
Modellwechsel. Der Wechsel von claude-sonnet-4-6 zu claude-opus-4-7 ist ein Cache-Miss. Der Cache ist pro Modell geschlüsselt. Das ist wichtig, wenn Sie Experimente fahren oder A/B-Routing zwischen Modellen nutzen.
Die 5-Minuten-TTL ist kurz. Für Batch-Jobs, die alle zehn Minuten laufen, bringt Caching nichts. Für einen aktiven Agent summiert es sich. Benötigen Sie längere Aufbewahrung, hat Anthropic erweiterte TTL-Optionen für bestimmte Stufen veröffentlicht, aber der Default sind fünf Minuten und danach sollten Sie planen.
Zusammenspiel von Prefill und Caching. Der Assistant-Prefill-Trick, den ich für strukturierte Ausgaben nutze, funktioniert einwandfrei mit Caching, solange der Prefill-Inhalt selbst stabil ist. Variiert der Prefill pro Request, cachen Sie ihn nicht.
Für Agent-Muster, bei denen Caching seinen Wert besonders ausspielt, behandelt der Artikel zu Claude Code SDK Agent-Mustern mehrstufige Workflows durchgängig, inklusive der Frage, wie wiederkehrende Tool-Definitionen das Token-Budget dominieren.
Wann Prompt Caching den Aufwand wert ist
Aktivieren Sie Prompt Caching, wenn:
- Sie einen stabilen Prefix über 1.024 Tokens (Sonnet/Opus) oder 2.048 Tokens (Haiku) haben
- Sie zwei oder mehr Aufrufe gegen diesen Prefix innerhalb von fünf Minuten erwarten
- Sie mehrstufige Konversationen, RAG-Pipelines oder tool-lastige Agents betreiben
- Ihr Verhältnis von Prefix zu Variablem hoch ist (grosser System-Prompt, kurze User-Nachrichten)
Verzichten Sie darauf, wenn:
- Aufrufe einmalig sind oder stundenweit auseinander liegen
- Der Prefix bei jedem Aufruf wechselt (dynamisches RAG mit pro Query einzigartigen Dokumenten)
- Ihr Prompt unter der Mindest-Token-Schwelle liegt
- Sie prototypisieren und der Instrumentierungsaufwand die Cents nicht rechtfertigt
Die Entscheidung dreht sich nicht darum, ob Caching “besser” ist. Sie dreht sich darum, ob Ihr Workload die Form hat, bei der der 10x-Read-Rabatt den 1,25x-Write-Aufschlag übertrifft. Rechnen Sie mit Ihrem tatsächlichen Aufrufmuster, loggen Sie cache_read_input_tokens bei jeder Antwort und setzen Sie einen Alarm, wenn die Trefferquote sinkt. So wissen Sie, dass Caching wirklich leistet, was Sie von ihm erwarten.