SpyBara
Go Premium

agent-sdk/cost-tracking.md 2026-10-01 23:59 UTC to 2026-10-02 15:01 UTC

This page contains 144 additions and 66 deletions.

2026
Fri 2 16:01

Kosten und Nutzung nachverfolgen

Erfahren Sie, wie Sie mit dem Claude Agent SDK die Token-Nutzung nachverfolgen, Kosten schätzen und Prompt-Caching konfigurieren.

Das Claude Agent SDK liefert detaillierte Informationen zur Token-Nutzung für jede Interaktion mit Claude. Dieser Leitfaden erklärt, wie Sie die Nutzung korrekt nachverfolgen und die Kostenberichte verstehen, insbesondere bei paralleler Tool-Nutzung und mehrstufigen Konversationen.

Die vollständige API-Dokumentation finden Sie in der TypeScript SDK-Referenz und der Python SDK-Referenz.

Token-Nutzung verstehen

Die TypeScript- und Python-SDKs stellen dieselben Nutzungsdaten mit unterschiedlichen Feldnamen bereit:

  • TypeScript bietet Token-Aufschlüsselungen pro Schritt für jede Assistenten-Nachricht (message.message.id, message.message.usage), Kosten pro Modell über modelUsage in der Ergebnisnachricht sowie eine kumulierte Gesamtsumme in der Ergebnisnachricht.
  • Python bietet Token-Aufschlüsselungen pro Schritt für jede Assistenten-Nachricht als message.usage und message.message_id, Kosten pro Modell über model_usage in der Ergebnisnachricht sowie die kumulierte Gesamtsumme in der Ergebnisnachricht als total_cost_usd.

Beide SDKs verwenden dasselbe zugrunde liegende Kostenmodell und bieten dieselbe Granularität. Der Unterschied liegt in der Benennung der Felder und darin, wo die Nutzung pro Schritt verschachtelt ist.

Die Kostenverfolgung setzt voraus, dass Sie verstehen, wie das SDK Nutzungsdaten abgrenzt:

  • query()-Aufruf: ein Aufruf der query()-Funktion des SDK. Ein einzelner Aufruf kann mehrere Schritte umfassen: Claude antwortet, verwendet Tools, erhält Ergebnisse und antwortet erneut. Jeder Aufruf erzeugt am Ende eine result-Nachricht, außer im Streaming-Eingabemodus, in dem ein query()-Aufruf mehrere Benutzer-Turns umfasst und jeder Turn seine eigene result-Nachricht ausgibt.
  • Schritt: ein einzelner Anfrage-/Antwort-Zyklus innerhalb eines query()-Aufrufs. Jeder Schritt erzeugt Assistenten-Nachrichten mit Token-Nutzung.
  • Sitzung: eine Reihe von query()-Aufrufen, die über eine Sitzungs-ID mithilfe der Option resume verknüpft sind. Die Ergebnisse eines fortgesetzten Aufrufs geben die gesamten Ausgaben der Sitzung an, nicht nur die des jeweiligen Aufrufs. Unter Kosten über mehrere Aufrufe hinweg kumulieren erfahren Sie, wie die Summen übernommen werden.

Das folgende Diagramm zeigt den Nachrichtenstrom eines einzelnen query()-Aufrufs, wobei die Token-Nutzung bei jedem Schritt und die kumulierte Schätzung am Ende gemeldet werden:

Diagramm, das eine Abfrage zeigt, die zwei Schritte von Nachrichten erzeugt. Schritt 1 hat vier Assistenten-Nachrichten mit derselben ID und Nutzung (einmal zählen), Schritt 2 hat eine Assistenten-Nachricht mit einer neuen ID, und die abschließende Ergebnisnachricht zeigt die geschätzten total_cost_usd. Diagramm, das eine Abfrage zeigt, die zwei Schritte von Nachrichten erzeugt. Schritt 1 hat vier Assistenten-Nachrichten mit derselben ID und Nutzung (einmal zählen), Schritt 2 hat eine Assistenten-Nachricht mit einer neuen ID, und die abschließende Ergebnisnachricht zeigt die geschätzten total_cost_usd.
1

Jeder Schritt erzeugt Assistenten-Nachrichten

Wenn Claude antwortet, sendet es eine oder mehrere Assistenten-Nachrichten. In TypeScript enthält jede Assistenten-Nachricht eine verschachtelte BetaMessage (Zugriff über message.message) mit einer id und einem usage-Objekt mit Token-Zählungen (input_tokens, output_tokens). In Python stellt die Dataclass AssistantMessage dieselben Daten direkt über message.usage und message.message_id bereit. Wenn Claude mehrere Tools in einem Turn verwendet, teilen alle Nachrichten in diesem Turn dieselbe ID. Deduplizieren Sie daher nach ID, um Doppelzählungen zu vermeiden.

2

Die Ergebnisnachricht liefert die kumulierte Schätzung

Wenn der query()-Aufruf abgeschlossen ist, gibt das SDK eine Ergebnisnachricht mit total_cost_usd und kumulierter usage aus, typisiert als SDKResultMessage in TypeScript und ResultMessage in Python. Wenn Sie nur die geschätzte Gesamtsumme benötigen, können Sie die Nutzung pro Schritt ignorieren und diesen einzelnen Wert auslesen.

Wenn Sie mehrere unabhängige query()-Aufrufe durchführen, spiegelt jedes Ergebnis nur die Kosten des jeweiligen Aufrufs wider. Ein Aufruf, der eine Sitzung fortsetzt, zählt auch die früheren Ausgaben der Sitzung mit.

Im Streaming-Eingabemodus gibt jeder Turn seine eigene Ergebnisnachricht aus. Unter Kosten im Streaming-Eingabemodus verfolgen erfahren Sie, wie Sie in diesem Modus die Gesamtsummen der Aufrufe auslesen.

Kosten im Streaming-Eingabemodus verfolgen

Im Streaming-Eingabemodus umfasst ein einzelner query()-Aufruf mehrere Benutzer-Turns, und jeder Turn gibt seine eigene Ergebnisnachricht aus. Die Ergebnisfelder unterscheiden sich in ihrem Umfang:

  • usage: umfasst nur diesen Turn und darin nur die Hauptagentenschleife, nicht die Subagenten, die sie ausgeführt hat.
  • total_cost_usd und modelUsage bzw. model_usage in Python: enthalten die laufende Gesamtsumme für den gesamten bisherigen Aufruf sowie alle Ausgaben, die wiederhergestellt wurden, als der Aufruf eine Sitzung fortgesetzt hat.

Lesen Sie in einem Aufruf, in dem Ihre App niemals /clear, /reset oder /new sendet, das neueste Ergebnis für die Gesamtsummen des Aufrufs, anstatt über alle Ergebnisse zu summieren.

Die laufenden Gesamtsummen beginnen jedes Mal neu, wenn Ihre App einen dieser drei Befehle sendet, und innerhalb eines query()-Aufrufs setzt sie nichts anderes zurück. Drei Ergebnisse sind für Ihre Abrechnung relevant:

  • Das eigene Ergebnis des /clear-Turns: umfasst nur das, was seit dem Zurücksetzen ausgeführt wurde, und enthält eine neue session_id.
  • Jedes spätere Ergebnis: zählt ab diesem Zurücksetzen weiter.
  • Das letzte Ergebnis vor jedem /clear: enthält die Gesamtsumme für die Turns seit dem vorherigen Zurücksetzen.

Um die Gesamtsumme des gesamten Aufrufs zu ermitteln, addieren Sie das letzte Ergebnis vor jedem /clear zum abschließenden Ergebnis des Aufrufs. Jedes andere Ergebnis, einschließlich des eigenen Ergebnisses des /clear-Turns, wird durch ein späteres ersetzt.

In TypeScript gibt das SDK bei jedem Zurücksetzen außerdem eine SDKConversationResetMessage aus, sodass Sie Zurücksetzungen im Stream erkennen können. In Python gibt das SDK entsprechend eine ConversationResetMessage aus. Vor Python SDK v0.2.137 hat der Python-Iterator diese Nachricht verworfen; zählen Sie die Zurücksetzungen bei diesen Versionen daher selbst anhand der /clear-Turns, die Ihre App sendet.

maxBudgetUsd (TypeScript) bzw. max_budget_usd (Python) zählt nur die eigenen Ausgaben des Aufrufs: Aus einer fortgesetzten Sitzung wiederhergestellte Gesamtsummen werden nicht darauf angerechnet, und ein /clear lässt das Budget von vorne beginnen.

Die Gesamtkosten einer Abfrage ermitteln

Die Ergebnisnachricht, in TypeScript als SDKResultMessage und in Python als ResultMessage typisiert, markiert das Ende der Agentenschleife für einen query()-Aufruf. Sie enthält total_cost_usd, die kumulierten geschätzten Kosten über alle Schritte dieses Aufrufs. Ein Aufruf, der eine Sitzung fortsetzt, zählt auch die früheren Ausgaben der Sitzung mit. Beim Auslesen des Werts gelten zwei Einschränkungen:

  • In Python ist das Feld als optional typisiert. Prüfen Sie daher, dass es nicht None ist, bevor Sie es auslesen.
  • Sowohl Erfolgs- als auch Fehlerergebnisse enthalten es, allerdings kann das endgültige Ergebnis nach einem Sitzungsabsturz den Wert auf null gesetzt enthalten.

Im Streaming-Eingabemodus lesen Sie die Aufrufsummen wie unter Kosten im Streaming-Eingabemodus verfolgen beschrieben aus.

Die drei Felder auf Ergebnisebene unterscheiden sich darin, was sie zählen, wenn der Agent Subagenten startet. Verwenden Sie modelUsage bzw. model_usage in Python für die Token-Abrechnung über den gesamten Baum; das Feld usage zählt zu wenig, sobald eine Verschachtelung auftritt.

Feld Aktivität von Subagenten
usage Ausgeschlossen. Zählt nur die Agentenschleife der obersten Ebene, sodass innerhalb von Subagenten verbrauchte Token nicht hinzugerechnet werden
total_cost_usd Eingeschlossen. Zählt Anfragen von Subagenten zusammen mit der Schleife der obersten Ebene
modelUsage / model_usage Eingeschlossen. Zählt Anfragen von Subagenten zusammen mit der Schleife der obersten Ebene, aufgeschlüsselt nach Modell

Im Einzelnachrichten-Eingabemodus wartet Claude Code, wenn am Ende des letzten Turns noch Subagenten im Hintergrund laufen, bis zu der unter Hintergrundaufgaben beim Beenden beschriebenen Obergrenze auf diese, bevor das Ergebnis ausgegeben wird. Die Werte total_cost_usd, duration_api_ms und modelUsage bzw. model_usage in Python des Ergebnisses schließen die während dieser Wartezeit geleistete Arbeit ein.

Die folgenden Beispiele durchlaufen den Nachrichtenstrom eines query()-Aufrufs und geben die Gesamtkosten aus, sobald die result-Nachricht eintrifft:

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
for await (const message of query({ prompt: "Summarize this project" })) {
if (message.type === "result") {
console.log(`Total cost: $${message.total_cost_usd}`);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, it still carried total_cost_usd and the
// branch above has already run; connection or process failures yield
// no result message.
console.error(`Session ended with an error: ${error}`);
}

Um zu begrenzen, wie viel Subagenten zu total_cost_usd beitragen können, legen Sie für die Abfrage die Limits für Tiefe, Parallelität und Ausgaben fest.

Nutzung pro Schritt und pro Modell verfolgen

Die Beispiele in diesem Abschnitt verwenden TypeScript-Feldnamen. In Python sind die entsprechenden Felder AssistantMessage.usage und AssistantMessage.message_id für die Nutzung pro Schritt sowie ResultMessage.model_usage für Aufschlüsselungen pro Modell.

Nutzung pro Schritt verfolgen

Jede Assistant-Nachricht enthält eine verschachtelte BetaMessage (Zugriff über message.message) mit einer id und einem usage-Objekt mit Token-Zählungen. Wenn Claude Tools parallel verwendet, teilen sich mehrere Nachrichten dieselbe id mit identischen Nutzungsdaten. Verfolgen Sie, welche IDs Sie bereits gezählt haben, und überspringen Sie Duplikate, um überhöhte Summen zu vermeiden.

Das folgende Beispiel summiert die Eingabe-Token über alle Schritte hinweg, wobei jede eindeutige Nachrichten-ID der Hauptschleife nur einmal gezählt und Nachrichten von Subagenten übersprungen werden. Die Gesamtzahl der Ausgabe-Token wird aus der Ergebnisnachricht gelesen, die die Hauptschleife abdeckt:

import { query } from "@anthropic-ai/claude-agent-sdk";

const seenIds = new Set<string>();
let totalInputTokens = 0;
let resultOutputTokens = 0;

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant" && !message.parent_tool_use_id) {
      const msgId = message.message.id;

      // Parallel tool calls share the same ID, only count once
      if (!seenIds.has(msgId)) {
        seenIds.add(msgId);
        totalInputTokens += message.message.usage.input_tokens;
      }
    }
    if (message.type === "result") {
      // Per-step output_tokens is a placeholder; the result message
      // carries the accumulated output total.
      resultOutputTokens = message.usage.output_tokens;
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result, so the
  // input total below still reflects the steps that ran before the failure.
  console.error(`Session ended with an error: ${error}`);
}

console.log(`Steps: ${seenIds.size}`);
console.log(`Input tokens: ${totalInputTokens}`);
console.log(`Output tokens: ${resultOutputTokens}`);

Nutzung pro Modell aufschlüsseln

Die Ergebnisnachricht enthält modelUsage, eine Zuordnung von Modellnamen zu Token-Zählungen und Kosten pro Modell. Dies ist nützlich, wenn Sie mehrere Modelle ausführen (zum Beispiel Haiku für Subagenten und Opus für den Hauptagenten) und sehen möchten, wohin die Token fließen.

Das Feld costBasis jedes Eintrags gibt an, mit welcher Preistabelle die letzte Anfrage dieses Modells berechnet wurde: list für den Listenpreis, managed für eine modelPricing-Tabelle oder unknown, wenn keine der beiden auf die Modell-ID zutraf. Das Feld erfordert Claude Code v2.1.246 oder höher.

Das folgende Beispiel führt eine Abfrage aus und gibt die Kosten- und Token-Aufschlüsselung für jedes verwendete Modell aus:

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type !== "result") continue;

    for (const [modelName, usage] of Object.entries(message.modelUsage)) {
      console.log(`${modelName}: $${usage.costUSD.toFixed(4)}`);
      console.log(`  Input tokens: ${usage.inputTokens}`);
      console.log(`  Output tokens: ${usage.outputTokens}`);
      console.log(`  Cache read: ${usage.cacheReadInputTokens}`);
      console.log(`  Cache creation: ${usage.cacheCreationInputTokens}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the per-model breakdown above has already
  // printed; connection or process failures yield no result message.
  console.error(`Session ended with an error: ${error}`);
}

Kosten über mehrere Aufrufe hinweg akkumulieren

Jeder query()-Aufruf gibt in seinen Ergebnissen total_cost_usd zurück. Wie Sie die Werte kombinieren, hängt davon ab, ob die Aufrufe eine Sitzung gemeinsam nutzen:

  • Unabhängige Aufrufe ohne die Option resume oder continue: Jedes Ergebnis deckt nur den eigenen Aufruf ab, daher addieren Sie die Gesamtwerte selbst, wie es die folgenden Beispiele tun.
  • Aufrufe, die dieselbe Sitzung fortsetzen: Claude Code speichert die Gesamtwerte der Sitzung in ihrem Transkript, wenn der Prozess normal beendet wird, und stellt sie wieder her, wenn ein späterer Aufruf die Sitzung fortsetzt oder forkt. Jedes Ergebnis enthält bereits die früheren Ausgaben der Sitzung. Lesen Sie das neueste Ergebnis, um den Gesamtwert der Sitzung zu erhalten; wenn Sie die Ergebnisse summieren, werden die wiederhergestellten Ausgaben doppelt gezählt. Vor v2.1.277 begannen die Gesamtwerte einer Sitzung, die Sie über das SDK oder claude -p fortgesetzt haben, bei null, sodass die Ergebnisse jedes Aufrufs nur diesen Aufruf abdeckten.

Im Streaming-Eingabemodus lesen Sie den Gesamtwert jedes Aufrufs wie unter Kosten im Streaming-Eingabemodus verfolgen beschrieben. Für einen Aufruf, der mit einem Absturz endete, siehe Gesamtwerte nach einem Sitzungsabsturz wiederherstellen.

Die folgenden Beispiele führen zwei query()-Aufrufe nacheinander aus, addieren das total_cost_usd jedes Aufrufs zu einer laufenden Summe und geben sowohl die Kosten pro Aufruf als auch die kombinierten Kosten aus:

import { query } from "@anthropic-ai/claude-agent-sdk";

// Track cumulative cost across multiple query() calls
let totalSpend = 0;

const prompts = [
"Read the files in src/ and summarize the architecture",
"List all exported functions in src/auth.ts"
];

for (const prompt of prompts) {
try {
for await (const message of query({ prompt })) {
if (message.type === "result") {
totalSpend += message.total_cost_usd;
console.log(`This call: $${message.total_cost_usd}`);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, this call's cost was already counted;
// connection or process failures yield no result message. Continue
// with the next prompt.
console.error(`Call failed: ${error}`);
}
}

console.log(`Total spend: $${totalSpend.toFixed(4)}`);

Fehler, Caching und Ausgabe-Token-Zählungen behandeln

Für eine genaue Kostenverfolgung sollten Sie die Platzhalter-Ausgabezählung bei Assistentennachrichten, die von einer fehlgeschlagenen Konversation verbrauchten Token und die Preise für Cache-Token berücksichtigen.

Ausgabe-Token aus der Ergebnisnachricht lesen

Claude Code erstellt jede Assistentennachricht aus der Nutzung, die die API zu Beginn der Antwort gemeldet hat. Daher ist output_tokens einer Nachricht nur die Zählung, die die API bei message_start gemeldet hatte, bevor die Antwort generiert wurde. Eine API-Antwort kann mehrere Assistentennachrichten erzeugen, und jede von ihnen enthält denselben Platzhalter.

Die API meldet die tatsächliche Ausgabezählung am Ende der Antwort, und Claude Code fügt sie der Ergebnisnachricht hinzu. Lesen Sie Ausgabe-Token aus usage des Ergebnisses oder aus modelUsage für eine Aufschlüsselung pro Modell.

Um zu beobachten, wie die Ausgabezählung einer Antwort während des Streamings wächst, setzen Sie includePartialMessages bzw. include_partial_messages in Python und lesen Sie usage aus jedem message_delta-Stream-Event, typisiert als SDKPartialAssistantMessage in TypeScript und StreamEvent in Python.

Kosten bei fehlgeschlagenen Konversationen verfolgen

Sowohl Erfolgs- als auch Fehler-Ergebnisnachrichten enthalten usage und total_cost_usd. In Python sind beide Felder als optional typisiert, prüfen Sie also, dass sie nicht None sind, bevor Sie sie lesen.

Wenn eine Konversation mittendrin fehlschlägt, haben Sie bis zum Zeitpunkt des Fehlers trotzdem Token verbraucht. Lesen Sie Kostendaten aus jeder Ergebnisnachricht, unabhängig davon, ob ihr subtype success oder einer der Fehler-Subtypen ist. Bei einigen Fehlerergebnissen meldet usage weniger, als der Aufruf tatsächlich verbraucht hat:

  • error_during_execution nach einem Sitzungsabsturz: Alle Kostenfelder können auf null gesetzt sein.
  • error_max_budget_usd: usage lässt die Antwort aus, die das Budget überschritten hat, während total_cost_usd und modelUsage sie enthalten.

Wenn Sie die Wahl haben, rechnen Sie auf Basis von total_cost_usd oder modelUsage statt usage ab.

Summen nach einem Sitzungsabsturz wiederherstellen

Wenn der Claude-Code-Prozess abstürzt, gibt er ein abschließendes error_during_execution-Ergebnis aus und beendet sich, sowohl im Single-Shot- als auch im Streaming-Eingabemodus. Dieses Ergebnis kann auf null gesetzte Werte für usage, total_cost_usd und modelUsage enthalten. Stellen Sie die Summen des Aufrufs daher aus dem wieder her, was davor eingetroffen ist. Schritt 1 stellt die vollständigen Summen wieder her, sofern ein früheres Ergebnis existiert; der Fallback in Schritt 2 stellt nur die Eingabe- und Cache-Token der Hauptschleife wieder her.

  1. Verwenden Sie das Ergebnis des Turns vor dem Absturz. Im Streaming-Eingabemodus enthält es die laufende Summe, die unter Kosten im Streaming-Eingabemodus verfolgen beschrieben ist. Gehen Sie stattdessen zu Schritt 2, wenn Ihnen dieses Ergebnis nicht weiterhilft:
    • Der Aufruf war Single-Shot, daher existiert kein früheres Ergebnis.
    • Der Absturz trat im ersten Turn auf.
    • Der Turn vor dem Absturz war das /clear selbst, sodass sein Ergebnis nur das Zurücksetzen abdeckt.
  2. Summieren Sie stattdessen usage der Assistentennachrichten und zählen Sie jede API-Antwort nur einmal, wie es das Beispiel unter Nutzung pro Schritt verfolgen tut. Im Single-Shot-Modus summieren Sie alle; im Streaming-Eingabemodus summieren Sie diejenigen, die nach dem letzten Ergebnis eingetroffen sind. Dadurch erhalten Sie die Eingabe- und Cache-Token der Hauptschleife. Die Nutzung von Subagenten lässt sich auf diese Weise nicht wiederherstellen, ebenso wenig Ausgabe-Token oder USD-Kosten, da output_tokens pro Schritt ein Platzhalter ist.

Cache-Token verfolgen

Das Agent SDK verwendet automatisch Prompt-Caching, um die Kosten für wiederholte Inhalte zu senken. Sie müssen das Caching nicht selbst konfigurieren. Das Nutzungsobjekt enthält zwei zusätzliche Felder zur Cache-Verfolgung:

  • cache_creation_input_tokens: Token, die zum Erstellen neuer Cache-Einträge verwendet werden (zu einem höheren Tarif abgerechnet als Standard-Eingabe-Token).
  • cache_read_input_tokens: Token, die aus vorhandenen Cache-Einträgen gelesen werden (zu einem reduzierten Tarif abgerechnet).

Verfolgen Sie diese getrennt von input_tokens, um die Einsparungen durch Caching nachzuvollziehen. In TypeScript sind diese Felder im Usage-Objekt typisiert. In Python erscheinen sie als Schlüssel im Dict ResultMessage.usage (zum Beispiel message.usage.get("cache_read_input_tokens", 0)).

Die TTL des Prompt-Caches auf eine Stunde verlängern

Ihre eigenen Turns fallen in den TTL-Bereich der Hauptkonversation, zusammen mit den Hilfsanfragen, die Claude Code inline mit ihnen ausführt. Die Anfragen, die Claude Code außerhalb dieser Konversation stellt, etwa Subagenten, haben eine separate TTL-Steuerung.

Cache-Einträge für Ihre eigenen Turns verwenden standardmäßig eine TTL von 5 Minuten, wenn Sie sich mit einem API-Schlüssel authentifizieren oder auf Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry oder Claude Platform on AWS ausführen. Wenn Ihr Workload viele kurze Sitzungen mit demselben System-Prompt und Kontext ausführt und zwischen ihnen Pausen von mehr als 5 Minuten liegen, läuft der Cache zwischen den Sitzungen ab, und jede neue Sitzung zahlt den vollen Eingabepreis.

Um eine TTL von 1 Stunde für Cache-Schreibvorgänge anzufordern, setzen Sie die Umgebungsvariable ENABLE_PROMPT_CACHING_1H. Sie können sie in Ihrer Shell- oder Container-Umgebung exportieren oder über options.env übergeben.

Das folgende Beispiel aktiviert die 1-Stunden-TTL für einen Agenten, der auf Amazon Bedrock läuft. Da es CLAUDE_CODE_USE_BEDROCK setzt, benötigt es funktionierende AWS-Anmeldedaten für Amazon Bedrock; ohne diese schlägt die Abfrage fehl.

from claude_agent_sdk import ClaudeAgentOptions, query
import asyncio


async def main():
options = ClaudeAgentOptions(
env={
"CLAUDE_CODE_USE_BEDROCK": "1",
"ENABLE_PROMPT_CACHING_1H": "1",
},
)

async for message in query(prompt="Summarize this project", options=options):
print(message)


asyncio.run(main())

Cache-Schreibvorgänge mit einer TTL von 1 Stunde werden zu einem höheren Tarif abgerechnet als 5-Minuten-Schreibvorgänge. Durch das Aktivieren tauschen Sie also höhere Schreibkosten gegen mehr Cache-Lesevorgänge. Details finden Sie unter Preise für Prompt-Caching. Mit einem Claude-Abonnement erhalten Sie innerhalb der in Ihrem Plan enthaltenen Nutzung die 1-Stunden-TTL für Ihre eigenen Turns und für einige der Hilfsanfragen, die Claude Code daneben stellt, ohne diese Variable zu setzen. Claude Code stuft diese Turns auf die 5-Minuten-TTL herab, sobald Sie Nutzungsguthaben in Anspruch nehmen.

ENABLE_PROMPT_CACHING_1H fordert die 1-Stunden-TTL für jede Anfrage in beiden Bereichen an. Um für jeden Bereich separat eine TTL zu wählen, verwenden Sie stattdessen diese Steuerungen. Jede akzeptiert 5m oder 1h und hat Vorrang vor ENABLE_PROMPT_CACHING_1H:

Wenn Sie promptCacheTtl auf 1h setzen, bleibt der 1-Stunden-Cache für die Hauptkonversation erhalten, während Sie Nutzungsguthaben in Anspruch nehmen. Die vollständige Rangfolge finden Sie unter die TTL selbst wählen.