Skip to main content
Das Claude Agent SDK bietet detaillierte Token-Nutzungsinformationen für jede Interaktion mit Claude. Dieser Leitfaden erklärt, wie Sie die Nutzung ordnungsgemäß verfolgen und die Kostenberichterstattung verstehen, besonders bei parallelen Tool-Verwendungen und mehrstufigen Gesprächen. Für die vollständige API-Dokumentation siehe die TypeScript SDK-Referenz und Python SDK-Referenz.
Die Felder total_cost_usd und costUSD sind clientseitige Schätzungen, keine verbindlichen Abrechnungsdaten. Das SDK berechnet sie lokal aus einer Preistabelle, die zur Build-Zeit gebündelt wird, daher können sie von dem abweichen, was Sie tatsächlich abgerechnet bekommen, wenn:
  • sich die Preise ändern
  • die installierte SDK-Version ein Modell nicht erkennt
  • Abrechnungsregeln gelten, die der Client nicht modellieren kann
Verwenden Sie diese Felder für Entwicklungseinblicke und ungefähre Budgetierung. Für verbindliche Abrechnung verwenden Sie die Usage and Cost API oder die Seite „Nutzung” in der Claude Console. Berechnen Sie Endbenutzer nicht und treffen Sie keine finanziellen Entscheidungen basierend auf diesen Feldern.

​
Token-Nutzung verstehen

Die TypeScript- und Python-SDKs stellen die gleichen Nutzungsdaten mit unterschiedlichen Feldnamen bereit:
  • TypeScript bietet Token-Aufschlüsselungen pro Schritt auf jeder Assistenten-Nachricht (message.message.id, message.message.usage), Kosten pro Modell über modelUsage auf der Ergebnis-Nachricht und eine kumulative Summe auf der Ergebnis-Nachricht.
  • Python bietet Token-Aufschlüsselungen pro Schritt auf jeder Assistenten-Nachricht (message.usage, message.message_id), Kosten pro Modell über model_usage auf der Ergebnis-Nachricht und die akkumulierte Summe auf der Ergebnis-Nachricht (total_cost_usd und usage dict).
Beide SDKs verwenden das gleiche zugrunde liegende Kostenmodell und stellen die gleiche Granularität bereit. Der Unterschied liegt in der Feldbennung und wo die Nutzung pro Schritt verschachtelt ist. Die Kostenverfolgung hängt davon ab, zu verstehen, wie das SDK Nutzungsdaten umfasst:
  • query() Aufruf: eine Invokation der query() Funktion des SDK. Ein einzelner Aufruf kann mehrere Schritte beinhalten (Claude antwortet, verwendet Tools, erhält Ergebnisse, antwortet erneut). Jeder Aufruf erzeugt am Ende eine result Nachricht.
  • Schritt: ein einzelner Request/Response-Zyklus innerhalb eines query() Aufrufs. Jeder Schritt erzeugt Assistenten-Nachrichten mit Token-Nutzung.
  • Sitzung: eine Serie von query() Aufrufen, die durch eine Sitzungs-ID verknüpft sind (mit der resume Option). Jeder query() Aufruf innerhalb einer Sitzung meldet seine eigenen Kosten unabhängig.
Das folgende Diagramm zeigt den Nachrichtenstrom aus einem einzelnen query() Aufruf, mit Token-Nutzung, die bei jedem Schritt gemeldet wird, und der kumulativen Schätzung am Ende: Diagramm, das eine Abfrage zeigt, die zwei Schritte von Nachrichten erzeugt. Schritt 1 hat vier Assistenten-Nachrichten, die die gleiche ID und Nutzung teilen (einmal zählen), Schritt 2 hat eine Assistenten-Nachricht mit einer neuen ID, und die endgültige Ergebnis-Nachricht zeigt die geschätzte 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 (zugänglich über message.message) mit einer id und einem usage Objekt mit Token-Zählungen (input_tokens, output_tokens). In Python stellt die AssistantMessage Dataclass die gleichen Daten direkt über message.usage und message.message_id bereit. Wenn Claude mehrere Tools in einer Runde verwendet, teilen alle Nachrichten in dieser Runde die gleiche ID, daher deduplizieren Sie nach ID, um Doppelzählungen zu vermeiden.
2

Die Ergebnis-Nachricht bietet die kumulative Schätzung

Wenn der query() Aufruf abgeschlossen ist, gibt das SDK eine Ergebnis-Nachricht mit total_cost_usd und kumulativer usage aus. Dies ist in TypeScript (SDKResultMessage) und Python (ResultMessage) verfügbar. Wenn Sie mehrere query() Aufrufe tätigen (zum Beispiel in einer mehrstufigen Sitzung), spiegelt jedes Ergebnis nur die Kosten dieses einzelnen Aufrufs wider. Wenn Sie nur die geschätzte Summe benötigen, können Sie die Nutzung pro Schritt ignorieren und diesen einzelnen Wert lesen.

​
Gesamtkosten einer Abfrage abrufen

Die Ergebnis-Nachricht (TypeScript, Python) markiert das Ende der Agent-Schleife für einen query()-Aufruf. Sie enthält total_cost_usd, die geschätzte kumulative Kosten über alle Schritte in diesem Aufruf. Dies funktioniert sowohl für erfolgreiche als auch für Fehler-Ergebnisse. Wenn Sie Sitzungen verwenden, um mehrere query()-Aufrufe zu tätigen, spiegelt jedes Ergebnis nur die Kosten dieses einzelnen Aufrufs wider. Die drei Felder auf Ergebnis-Ebene unterscheiden sich darin, was sie zählen, wenn der Agent Subagenten erzeugt. Verwenden Sie modelUsage oder model_usage in Python für die Gesamtbaum-Token-Abrechnung; das Feld usage unterschätzt, sobald Verschachtelung auftritt. Die folgenden Beispiele durchlaufen den Nachrichtenstrom aus einem query()-Aufruf und geben die Gesamtkosten aus, wenn die result-Nachricht ankommt: