Die Kontextbearbeitung ermöglicht es Ihnen, den Gesprächskontext automatisch zu verwalten, während er wächst, und hilft Ihnen, Kosten zu optimieren und innerhalb der Kontextfenstergrenzen zu bleiben. Sie können Server-seitige API-Strategien, Client-seitige SDK-Funktionen oder beide zusammen verwenden.
| Ansatz | Wo es läuft | Strategien | Wie es funktioniert |
|---|---|---|---|
| Server-seitig | API | Tool-Ergebnis-Löschen (clear_tool_uses_20250919)Thinking-Block-Löschen ( clear_thinking_20251015) | Wird angewendet, bevor der Prompt Claude erreicht. Löscht spezifische Inhalte aus der Gesprächshistorie. Jede Strategie kann unabhängig konfiguriert werden. |
| Client-seitig | SDK | Komprimierung | Verfügbar in Python- und TypeScript-SDKs bei Verwendung von tool_runner. Generiert eine Zusammenfassung und ersetzt die vollständige Gesprächshistorie. Siehe Komprimierung unten. |
Die Kontextbearbeitung befindet sich derzeit in der Beta-Phase mit Unterstützung für Tool-Ergebnis-Löschen und Thinking-Block-Löschen. Um dies zu aktivieren, verwenden Sie den Beta-Header context-management-2025-06-27 in Ihren API-Anfragen.
Bitte kontaktieren Sie uns über unser Feedback-Formular, um Ihr Feedback zu dieser Funktion zu teilen.
Die Strategie clear_tool_uses_20250919 löscht Tool-Ergebnisse, wenn der Gesprächskontext über Ihren konfigurierten Schwellenwert hinauswächst. Wenn aktiviert, löscht die API automatisch die ältesten Tool-Ergebnisse in chronologischer Reihenfolge und ersetzt sie durch Platzhaltertext, um Claude wissen zu lassen, dass das Tool-Ergebnis entfernt wurde. Standardmäßig werden nur Tool-Ergebnisse gelöscht. Sie können optional sowohl Tool-Ergebnisse als auch Tool-Aufrufe (die Tool-Use-Parameter) löschen, indem Sie clear_tool_inputs auf true setzen.
Die Strategie clear_thinking_20251015 verwaltet thinking-Blöcke in Gesprächen, wenn erweitertes Denken aktiviert ist. Diese Strategie löscht automatisch ältere Thinking-Blöcke aus vorherigen Turns.
Standardverhalten: Wenn erweitertes Denken ohne Konfiguration der Strategie clear_thinking_20251015 aktiviert ist, behält die API automatisch nur die Thinking-Blöcke aus dem letzten Assistant-Turn bei (entspricht keep: {type: "thinking_turns", value: 1}).
Um Cache-Treffer zu maximieren, bewahren Sie alle Thinking-Blöcke auf, indem Sie keep: "all" setzen.
Ein Assistant-Gesprächsturn kann mehrere Inhaltsblöcke enthalten (z. B. bei Verwendung von Tools) und mehrere Thinking-Blöcke (z. B. mit verschachteltem Denken).
Kontextbearbeitung erfolgt server-seitig
Die Kontextbearbeitung wird server-seitig angewendet, bevor der Prompt Claude erreicht. Ihre Client-Anwendung behält die vollständige, unveränderte Gesprächshistorie bei – Sie müssen Ihren Client-Status nicht mit der bearbeiteten Version synchronisieren. Verwalten Sie Ihre vollständige Gesprächshistorie weiterhin lokal wie gewohnt.
Kontextbearbeitung und Prompt-Caching
Die Interaktion der Kontextbearbeitung mit Prompt-Caching variiert je nach Strategie:
Tool-Ergebnis-Löschen: Invalidiert zwischengespeicherte Prompt-Präfixe, wenn Inhalte gelöscht werden. Um dies zu berücksichtigen, empfehlen wir, genug Token zu löschen, um die Cache-Invalidierung lohnenswert zu machen. Verwenden Sie den Parameter clear_at_least, um sicherzustellen, dass jedes Mal eine Mindestanzahl von Token gelöscht wird. Sie entstehen Cache-Schreibkosten jedes Mal, wenn Inhalte gelöscht werden, aber nachfolgende Anfragen können das neu zwischengespeicherte Präfix wiederverwenden.
Thinking-Block-Löschen: Wenn Thinking-Blöcke behalten werden im Kontext (nicht gelöscht), wird der Prompt-Cache beibehalten, was Cache-Treffer ermöglicht und Eingabe-Token-Kosten reduziert. Wenn Thinking-Blöcke gelöscht werden, wird der Cache an der Stelle invalidiert, an der das Löschen erfolgt. Konfigurieren Sie den Parameter keep basierend darauf, ob Sie Cache-Leistung oder Kontextfensterverfügbarkeit priorisieren möchten.
Die Kontextbearbeitung ist verfügbar auf:
claude-opus-4-5-20251101)claude-opus-4-1-20250805)claude-opus-4-20250514)claude-sonnet-4-5-20250929)claude-sonnet-4-20250514)claude-haiku-4-5-20251001)Die einfachste Möglichkeit, das Tool-Ergebnis-Löschen zu aktivieren, besteht darin, nur den Strategietyp anzugeben, da alle anderen Konfigurationsoptionen ihre Standardwerte verwenden:
Sie können das Verhalten des Tool-Ergebnis-Löschens mit zusätzlichen Parametern anpassen:
Mit der Kontextbearbeitung können Sie den Gesprächskontext automatisch verwalten, während er wächst, um Kosten zu optimieren und innerhalb von Kontextfenstergrenzen zu bleiben. Sie können Server-seitige API-Strategien, Client-seitige SDK-Funktionen oder beide zusammen verwenden.
| Ansatz | Wo es ausgeführt wird | Strategien | Wie es funktioniert |
|---|---|---|---|
| Server-seitig | API | Tool-Ergebnis-Clearing (clear_tool_uses_20250919)Thinking-Block-Clearing ( clear_thinking_20251015) | Wird angewendet, bevor der Prompt Claude erreicht. Löscht spezifische Inhalte aus dem Gesprächsverlauf. Jede Strategie kann unabhängig konfiguriert werden. |
| Client-seitig | SDK | Komprimierung | Verfügbar in Python und TypeScript SDKs bei Verwendung von tool_runner. Generiert eine Zusammenfassung und ersetzt den vollständigen Gesprächsverlauf. Siehe Komprimierung unten. |
Die Kontextbearbeitung befindet sich derzeit in der Beta-Phase mit Unterstützung für Tool-Ergebnis-Clearing und Thinking-Block-Clearing. Um sie zu aktivieren, verwenden Sie den Beta-Header context-management-2025-06-27 in Ihren API-Anfragen.
Bitte teilen Sie Ihr Feedback zu dieser Funktion über unser Feedback-Formular mit.
Die Strategie clear_tool_uses_20250919 löscht Tool-Ergebnisse, wenn der Gesprächskontext über Ihren konfigurierten Schwellenwert hinauswächst. Wenn aktiviert, löscht die API automatisch die ältesten Tool-Ergebnisse in chronologischer Reihenfolge und ersetzt sie durch Platzhaltertext, um Claude mitzuteilen, dass das Tool-Ergebnis entfernt wurde. Standardmäßig werden nur Tool-Ergebnisse gelöscht. Sie können optional sowohl Tool-Ergebnisse als auch Tool-Aufrufe (die Tool-Use-Parameter) löschen, indem Sie clear_tool_inputs auf true setzen.
Die Strategie clear_thinking_20251015 verwaltet thinking-Blöcke in Gesprächen, wenn erweitertes Denken aktiviert ist. Diese Strategie löscht automatisch ältere Thinking-Blöcke aus vorherigen Turns.
Standardverhalten: Wenn erweitertes Denken ohne Konfiguration der Strategie clear_thinking_20251015 aktiviert ist, behält die API automatisch nur die Thinking-Blöcke aus dem letzten Assistant-Turn bei (entspricht keep: {type: "thinking_turns", value: 1}).
Um Cache-Treffer zu maximieren, bewahren Sie alle Thinking-Blöcke auf, indem Sie keep: "all" setzen.
Ein Assistant-Gesprächsturn kann mehrere Content-Blöcke enthalten (z. B. bei Verwendung von Tools) und mehrere Thinking-Blöcke (z. B. mit verschachteltem Denken).
Kontextbearbeitung erfolgt server-seitig
Die Kontextbearbeitung wird server-seitig angewendet, bevor der Prompt Claude erreicht. Ihre Client-Anwendung behält den vollständigen, unveränderten Gesprächsverlauf bei – Sie müssen Ihren Client-Status nicht mit der bearbeiteten Version synchronisieren. Verwalten Sie Ihren vollständigen Gesprächsverlauf lokal weiterhin wie gewohnt.
Kontextbearbeitung und Prompt-Caching
Die Interaktion der Kontextbearbeitung mit Prompt-Caching variiert je nach Strategie:
Tool-Ergebnis-Clearing: Invalidiert zwischengespeicherte Prompt-Präfixe, wenn Inhalte gelöscht werden. Um dies zu berücksichtigen, empfehlen wir, genug Token zu löschen, um die Cache-Invalidierung lohnenswert zu machen. Verwenden Sie den Parameter clear_at_least, um sicherzustellen, dass jedes Mal eine Mindestanzahl von Token gelöscht wird. Sie entstehen Cache-Schreibkosten jedes Mal, wenn Inhalte gelöscht werden, aber nachfolgende Anfragen können das neu zwischengespeicherte Präfix wiederverwenden.
Thinking-Block-Clearing: Wenn Thinking-Blöcke im Kontext behalten werden (nicht gelöscht), wird der Prompt-Cache beibehalten, was Cache-Treffer ermöglicht und Input-Token-Kosten reduziert. Wenn Thinking-Blöcke gelöscht werden, wird der Cache an der Stelle invalidiert, an der das Löschen erfolgt. Konfigurieren Sie den Parameter keep basierend darauf, ob Sie die Cache-Leistung oder die Verfügbarkeit des Kontextfensters priorisieren möchten.
Die Kontextbearbeitung ist verfügbar auf:
claude-opus-4-5-20251101)claude-opus-4-1-20250805)claude-opus-4-20250514)claude-sonnet-4-5-20250929)claude-sonnet-4-20250514)claude-haiku-4-5-20251001)Die einfachste Möglichkeit, Tool-Ergebnis-Clearing zu aktivieren, besteht darin, nur den Strategietyp anzugeben, da alle anderen Konfigurationsoptionen ihre Standardwerte verwenden:
Sie können das Verhalten des Tool-Ergebnis-Clearing mit zusätzlichen Parametern anpassen:
Aktivieren Sie Thinking-Block-Clearing, um den Kontext und das Prompt-Caching effektiv zu verwalten, wenn erweitertes Denken aktiviert ist:
Die Strategie clear_thinking_20251015 unterstützt die folgende Konfiguration:
| Konfigurationsoption | Standard | Beschreibung |
|---|---|---|
keep | {type: "thinking_turns", value: 1} | Definiert, wie viele neueste Assistant-Turns mit Thinking-Blöcken beibehalten werden sollen. Verwenden Sie {type: "thinking_turns", value: N}, wobei N > 0 sein muss, um die letzten N Turns zu behalten, oder "all", um alle Thinking-Blöcke zu behalten. |
Beispielkonfigurationen:
// Keep thinking blocks from the last 3 assistant turns
{
"type": "clear_thinking_20251015",
"keep": {
"type": "thinking_turns",
"value": 3
}
}
// Keep all thinking blocks (maximizes cache hits)
{
"type": "clear_thinking_20251015",
"keep": "all"
}Sie können Thinking-Block-Clearing und Tool-Ergebnis-Clearing zusammen verwenden:
Bei Verwendung mehrerer Strategien muss die Strategie clear_thinking_20251015 zuerst im Array edits aufgelistet werden.
| Konfigurationsoption | Standard | Beschreibung |
|---|---|---|
trigger | 100.000 Input-Token | Definiert, wann die Kontextbearbeitungsstrategie aktiviert wird. Sobald der Prompt diesen Schwellenwert überschreitet, beginnt das Löschen. Sie können diesen Wert entweder in input_tokens oder tool_uses angeben. |
keep | 3 Tool-Uses | Definiert, wie viele neueste Tool-Use/Result-Paare nach dem Löschen beibehalten werden sollen. Die API entfernt zuerst die ältesten Tool-Interaktionen und bewahrt die neuesten. |
clear_at_least | Keine | Stellt sicher, dass jedes Mal, wenn die Strategie aktiviert wird, eine Mindestanzahl von Token gelöscht wird. Wenn die API nicht mindestens die angegebene Menge löschen kann, wird die Strategie nicht angewendet. Dies hilft zu bestimmen, ob die Kontextbereinigung das Unterbrechen Ihres Prompt-Cache wert ist. |
exclude_tools | Keine | Liste von Tool-Namen, deren Tool-Uses und Ergebnisse niemals gelöscht werden sollten. Nützlich zum Bewahren wichtiger Kontexte. |
Sie können sehen, welche Kontextbearbeitungen auf Ihre Anfrage angewendet wurden, indem Sie das Antwortfeld context_management verwenden, zusammen mit hilfreichen Statistiken über den gelöschten Inhalt und die Input-Token.
{
"id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message",
"role": "assistant",
"content": [...],
"usage": {...},
"context_management": {
"applied_edits": [
// When using `clear_thinking_20251015`
{
"type": "clear_thinking_20251015",
"cleared_thinking_turns": 3,
"cleared_input_tokens": 15000
},
// When using `clear_tool_uses_20250919`
{
"type": "clear_tool_uses_20250919",
"cleared_tool_uses": 8,
"cleared_input_tokens": 50000
}
]
}
}Für Streaming-Antworten werden die Kontextbearbeitungen im finalen message_delta-Event enthalten:
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"stop_sequence": null
},
"usage": {
"output_tokens": 1024
},
"context_management": {
"applied_edits": [...]
}
}Die clear_thinking_20251015-Strategie unterstützt die folgende Konfiguration:
| Konfigurationsoption | Standard | Beschreibung |
|---|---|---|
keep | {type: "thinking_turns", value: 1} | Definiert, wie viele aktuelle Assistent-Turns mit Thinking Blocks beibehalten werden sollen. Verwenden Sie {type: "thinking_turns", value: N}, wobei N > 0 sein muss, um die letzten N Turns beizubehalten, oder "all", um alle Thinking Blocks beizubehalten. |
Beispielkonfigurationen:
// Thinking Blocks aus den letzten 3 Assistent-Turns beibehalten
{
"type": "clear_thinking_20251015",
"keep": {
"type": "thinking_turns",
"value": 3
}
}
// Alle Thinking Blocks beibehalten (maximiert Cache-Treffer)
{
"type": "clear_thinking_20251015",
"keep": "all"
}Sie können das Löschen von Thinking Blocks und das Löschen von Tool-Ergebnissen zusammen verwenden:
Wenn Sie mehrere Strategien verwenden, muss die clear_thinking_20251015-Strategie zuerst im edits-Array aufgelistet werden.
| Konfigurationsoption | Standard | Beschreibung |
|---|---|---|
trigger | 100.000 Input-Token | Definiert, wann die Kontextbearbeitungsstrategie aktiviert wird. Sobald der Prompt diesen Schwellenwert überschreitet, beginnt das Löschen. Sie können diesen Wert entweder in input_tokens oder tool_uses angeben. |
keep | 3 Tool-Verwendungen | Definiert, wie viele aktuelle Tool-Use/Result-Paare nach dem Löschen beibehalten werden sollen. Die API entfernt zuerst die ältesten Tool-Interaktionen und behält die neuesten bei. |
clear_at_least | Keine | Stellt sicher, dass jedes Mal, wenn die Strategie aktiviert wird, mindestens eine bestimmte Anzahl von Token gelöscht wird. Wenn die API nicht mindestens die angegebene Menge löschen kann, wird die Strategie nicht angewendet. Dies hilft zu bestimmen, ob das Löschen von Kontext das Unterbrechen Ihres Prompt-Cache wert ist. |
exclude_tools | Keine | Liste von Tool-Namen, deren Tool-Verwendungen und Ergebnisse niemals gelöscht werden sollten. Nützlich zum Beibehalten wichtiger Kontexte. |
Sie können sehen, welche Kontextbearbeitungen auf Ihre Anfrage angewendet wurden, indem Sie das context_management-Antwortfeld verwenden, zusammen mit hilfreichen Statistiken über den gelöschten Inhalt und die gelöschten Input-Token.
{
"id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message",
"role": "assistant",
"content": [...],
"usage": {...},
"context_management": {
"applied_edits": [
// Bei Verwendung von `clear_thinking_20251015`
{
"type": "clear_thinking_20251015",
"cleared_thinking_turns": 3,
"cleared_input_tokens": 15000
},
// Bei Verwendung von `clear_tool_uses_20250919`
{
"type": "clear_tool_uses_20250919",
"cleared_tool_uses": 8,
"cleared_input_tokens": 50000
}
]
}
}Bei Streaming-Antworten werden die Kontextbearbeitungen im finalen message_delta-Event enthalten sein:
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"stop_sequence": null
},
"usage": {
"output_tokens": 1024
},
"context_management": {
"applied_edits": [...]
}
}Der Token-Zählungs-Endpunkt unterstützt Kontextverwaltung, sodass Sie eine Vorschau erhalten können, wie viele Token Ihr Prompt nach Anwendung der Kontextbearbeitung verwenden wird.
{
"input_tokens": 25000,
"context_management": {
"original_input_tokens": 70000
}
}Die Antwort zeigt sowohl die endgültige Token-Anzahl nach Anwendung der Kontextverwaltung (input_tokens) als auch die ursprüngliche Token-Anzahl vor dem Löschen (original_input_tokens).
Die Kontextbearbeitung kann mit dem Memory Tool kombiniert werden. Wenn sich Ihr Gesprächskontext dem konfigurierten Lösch-Schwellenwert nähert, erhält Claude automatisch eine Warnung, um wichtige Informationen zu bewahren. Dies ermöglicht Claude, Tool-Ergebnisse oder Kontext in seinen Memory-Dateien zu speichern, bevor sie aus dem Gesprächsverlauf gelöscht werden.
Diese Kombination ermöglicht es Ihnen:
Beispielsweise kann Claude in einem Datei-Bearbeitungs-Workflow, in dem Claude viele Operationen durchführt, abgeschlossene Änderungen in Memory-Dateien zusammenfassen, während der Kontext wächst. Wenn Tool-Ergebnisse gelöscht werden, behält Claude Zugriff auf diese Informationen durch sein Memory-System und kann effektiv weiterarbeiten.
Um beide Funktionen zusammen zu verwenden, aktivieren Sie sie in Ihrer API-Anfrage:
Die Komprimierung ist in den Python- und TypeScript-SDKs verfügbar, wenn die tool_runner-Methode verwendet wird.
Die Komprimierung ist eine SDK-Funktion, die den Gesprächskontext automatisch verwaltet, indem Zusammenfassungen generiert werden, wenn die Token-Nutzung zu groß wird. Im Gegensatz zu serverseitigen Kontextbearbeitungsstrategien, die Inhalte löschen, weist die Komprimierung Claude an, den Gesprächsverlauf zusammenzufassen, und ersetzt dann den vollständigen Verlauf durch diese Zusammenfassung. Dies ermöglicht Claude, an langfristigen Aufgaben zu arbeiten, die sonst das Kontextfenster überschreiten würden.
Wenn die Komprimierung aktiviert ist, überwacht das SDK die Token-Nutzung nach jeder Modell-Antwort:
input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens<summary></summary>-Tags eingewickelt istFügen Sie compaction_control zu Ihrem tool_runner-Aufruf hinzu:
Während das Gespräch wächst, sammelt sich der Nachrichtenverlauf an:
Vor der Komprimierung (nähert sich 100k Token):
[
{ "role": "user", "content": "Analyze all files and write a report..." },
{ "role": "assistant", "content": "I'll help. Let me start by reading..." },
{ "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }] },
{ "role": "assistant", "content": "Based on file1.txt, I see..." },
{ "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }] },
{ "role": "assistant", "content": "After analyzing file2.txt..." },
// ... 50 more exchanges like this ...
]Wenn Token den Schwellenwert überschreiten, fügt das SDK eine Zusammenfassungsanfrage ein und Claude generiert eine Zusammenfassung. Der gesamte Verlauf wird dann ersetzt:
Nach der Komprimierung (zurück zu ~2-3k Token):
[
{
"role": "assistant",
"content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
}
]Claude setzt die Arbeit von dieser Zusammenfassung aus fort, als wäre es der ursprüngliche Gesprächsverlauf.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
enabled | boolean | Ja | - | Ob automatische Komprimierung aktiviert werden soll |
context_token_threshold | number | Nein | 100.000 | Token-Anzahl, bei der die Komprimierung ausgelöst wird |
model | string | Nein | Gleiches wie Hauptmodell | Modell zur Verwendung für die Zusammenfassungsgenerierung |
summary_prompt | string | Nein | Siehe unten | Benutzerdefinierte Aufforderung für die Zusammenfassungsgenerierung |
Der Schwellenwert bestimmt, wann die Komprimierung auftritt. Ein niedrigerer Schwellenwert bedeutet häufigere Komprimierungen mit kleineren Kontextfenstern. Ein höherer Schwellenwert ermöglicht mehr Kontext, riskiert aber, Grenzen zu erreichen.
# Häufigere Komprimierung für speicherbegrenzte Szenarien
compaction_control={
"enabled": True,
"context_token_threshold": 50000
}
# Weniger häufige Komprimierung, wenn Sie mehr Kontext benötigen
compaction_control={
"enabled": True,
"context_token_threshold": 150000
}Sie können ein schnelleres oder günstigeres Modell zur Generierung von Zusammenfassungen verwenden:
compaction_control={
"enabled": True,
"context_token_threshold": 100000,
"model": "claude-haiku-4-5"
}Sie können eine benutzerdefinierte Aufforderung für domänenspezifische Anforderungen bereitstellen. Ihre Aufforderung sollte Claude anweisen, seine Zusammenfassung in <summary></summary>-Tags einzuwickeln.
compaction_control={
"enabled": True,
"context_token_threshold": 100000,
"summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps
Wrap your summary in <summary></summary> tags."""
}Die Kontextbearbeitung kann mit dem Memory Tool kombiniert werden. Wenn sich Ihr Gesprächskontext dem konfigurierten Löschschwellenwert nähert, erhält Claude eine automatische Warnung, um wichtige Informationen zu bewahren. Dies ermöglicht es Claude, Tool-Ergebnisse oder Kontext in seinen Memory-Dateien zu speichern, bevor sie aus dem Gesprächsverlauf gelöscht werden.
Diese Kombination ermöglicht es Ihnen:
Beispielsweise kann Claude in einem Dateibearbeitungs-Workflow, in dem Claude viele Operationen durchführt, abgeschlossene Änderungen in Memory-Dateien zusammenfassen, während der Kontext wächst. Wenn Tool-Ergebnisse gelöscht werden, behält Claude Zugriff auf diese Informationen durch sein Memory-System und kann effektiv weiterarbeiten.
Um beide Funktionen zusammen zu verwenden, aktivieren Sie sie in Ihrer API-Anfrage:
Die Komprimierung ist in den Python und TypeScript SDKs verfügbar, wenn die tool_runner Methode verwendet wird.
Die Komprimierung ist eine SDK-Funktion, die den Gesprächskontext automatisch verwaltet, indem Zusammenfassungen generiert werden, wenn die Token-Nutzung zu groß wird. Im Gegensatz zu serverseitigen Kontextbearbeitungsstrategien, die Inhalte löschen, weist die Komprimierung Claude an, den Gesprächsverlauf zusammenzufassen, und ersetzt dann den vollständigen Verlauf durch diese Zusammenfassung. Dies ermöglicht es Claude, an langfristigen Aufgaben zu arbeiten, die sonst das Kontextfenster überschreiten würden.
Wenn die Komprimierung aktiviert ist, überwacht das SDK die Token-Nutzung nach jeder Modellantwort:
input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens<summary></summary> Tags eingewickelt istFügen Sie compaction_control zu Ihrem tool_runner Aufruf hinzu:
Während das Gespräch wächst, sammelt sich der Nachrichtenverlauf an:
Vor der Komprimierung (nähert sich 100k Tokens):
[
{ "role": "user", "content": "Analyze all files and write a report..." },
{ "role": "assistant", "content": "I'll help. Let me start by reading..." },
{ "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }] },
{ "role": "assistant", "content": "Based on file1.txt, I see..." },
{ "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }] },
{ "role": "assistant", "content": "After analyzing file2.txt..." },
// ... 50 more exchanges like this ...
]Wenn Tokens den Schwellenwert überschreiten, fügt das SDK eine Zusammenfassungsanfrage ein und Claude generiert eine Zusammenfassung. Der gesamte Verlauf wird dann ersetzt:
Nach der Komprimierung (zurück zu ~2-3k Tokens):
[
{
"role": "assistant",
"content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
}
]Claude setzt die Arbeit von dieser Zusammenfassung aus fort, als wäre es der ursprüngliche Gesprächsverlauf.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
enabled | boolean | Ja | - | Ob automatische Komprimierung aktiviert werden soll |
context_token_threshold | number | Nein | 100,000 | Token-Anzahl, bei der die Komprimierung ausgelöst wird |
model | string | Nein | Gleiches wie Hauptmodell | Modell zur Verwendung für die Zusammenfassungsgenerierung |
summary_prompt | string | Nein | Siehe unten | Benutzerdefinierte Aufforderung für die Zusammenfassungsgenerierung |
Der Schwellenwert bestimmt, wann die Komprimierung auftritt. Ein niedrigerer Schwellenwert bedeutet häufigere Komprimierungen mit kleineren Kontextfenstern. Ein höherer Schwellenwert ermöglicht mehr Kontext, birgt aber das Risiko, Grenzen zu erreichen.
# More frequent compaction for memory-constrained scenarios
compaction_control={
"enabled": True,
"context_token_threshold": 50000
}
# Less frequent compaction when you need more context
compaction_control={
"enabled": True,
"context_token_threshold": 150000
}Sie können ein schnelleres oder günstigeres Modell zur Generierung von Zusammenfassungen verwenden:
compaction_control={
"enabled": True,
"context_token_threshold": 100000,
"model": "claude-haiku-4-5"
}Sie können eine benutzerdefinierte Aufforderung für domänenspezifische Anforderungen bereitstellen. Ihre Aufforderung sollte Claude anweisen, seine Zusammenfassung in <summary></summary> Tags einzuwickeln.
compaction_control={
"enabled": True,
"context_token_threshold": 100000,
"summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps
Wrap your summary in <summary></summary> tags."""
}Die integrierte Zusammenfassungsaufforderung weist Claude an, eine strukturierte Fortsetzungszusammenfassung zu erstellen, die Folgendes enthält:
Diese Struktur ermöglicht es Claude, die Arbeit effizient fortzusetzen, ohne wichtigen Kontext zu verlieren oder Fehler zu wiederholen.
Die Komprimierung erfordert besondere Überlegung bei der Verwendung von serverseitigen Tools wie Web Search oder Web Fetch.
Bei Verwendung von serverseitigen Tools kann das SDK die Token-Nutzung falsch berechnen, was dazu führt, dass die Komprimierung zum falschen Zeitpunkt ausgelöst wird.
Beispielsweise könnte die API-Antwort nach einer Web-Search-Operation wie folgt aussehen:
{
"usage": {
"input_tokens": 63000,
"cache_read_input_tokens": 270000,
"output_tokens": 1400
}
}Das SDK berechnet die Gesamtnutzung als 63.000 + 270.000 = 333.000 Tokens. Der cache_read_input_tokens Wert umfasst jedoch akkumulierte Lesevorgänge aus mehreren internen API-Aufrufen, die vom serverseitigen Tool durchgeführt werden, nicht Ihren tatsächlichen Gesprächskontext. Ihre tatsächliche Kontextlänge könnte nur die 63.000 input_tokens sein, aber das SDK sieht 333k und löst die Komprimierung vorzeitig aus.
Lösungsansätze:
Wenn die Komprimierung ausgelöst wird, während eine Tool-Use-Antwort ausstehend ist, entfernt das SDK den Tool-Use-Block aus dem Nachrichtenverlauf, bevor die Zusammenfassung generiert wird. Claude wird den Tool-Aufruf nach der Wiederaufnahme aus der Zusammenfassung bei Bedarf erneut ausstellen.
Aktivieren Sie die Protokollierung, um zu verfolgen, wann die Komprimierung auftritt:
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)
# Logs will show:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500Gute Anwendungsfälle:
Weniger ideale Anwendungsfälle:
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "anthropic-beta: context-management-2025-06-27" \
--data '{
"model": "claude-sonnet-4-5",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": "Search for recent developments in AI"
}
],
"tools": [
{
"type": "web_search_20250305",
"name": "web_search"
}
],
"context_management": {
"edits": [
{"type": "clear_tool_uses_20250919"}
]
}
}'curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "anthropic-beta: context-management-2025-06-27" \
--data '{
"model": "claude-sonnet-4-5",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": "Create a simple command line calculator app using Python"
}
],
"tools": [
{
"type": "text_editor_20250728",
"name": "str_replace_based_edit_tool",
"max_characters": 10000
},
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 3
}
],
"context_management": {
"edits": [
{
"type": "clear_tool_uses_20250919",
"trigger": {
"type": "input_tokens",
"value": 30000
},
"keep": {
"type": "tool_uses",
"value": 3
},
"clear_at_least": {
"type": "input_tokens",
"value": 5000
},
"exclude_tools": ["web_search"]
}
]
}
}'curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "anthropic-beta: context-management-2025-06-27" \
--data '{
"model": "claude-sonnet-4-5",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": "Search for recent developments in AI"
}
],
"tools": [
{
"type": "web_search_20250305",
"name": "web_search"
}
],
"context_management": {
"edits": [
{"type": "clear_tool_uses_20250919"}
]
}
}'curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "anthropic-beta: context-management-2025-06-27" \
--data '{
"model": "claude-sonnet-4-5",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": "Create a simple command line calculator app using Python"
}
],
"tools": [
{
"type": "text_editor_20250728",
"name": "str_replace_based_edit_tool",
"max_characters": 10000
},
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 3
}
],
"context_management": {
"edits": [
{
"type": "clear_tool_uses_20250919",
"trigger": {
"type": "input_tokens",
"value": 30000
},
"keep": {
"type": "tool_uses",
"value": 3
},
"clear_at_least": {
"type": "input_tokens",
"value": 5000
},
"exclude_tools": ["web_search"]
}
]
}
}'curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "anthropic-beta: context-management-2025-06-27" \
--data '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"messages": [...],
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"context_management": {
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {
"type": "thinking_turns",
"value": 2
}
}
]
}
}'response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[...],
thinking={
"type": "enabled",
"budget_tokens": 10000
},
tools=[...],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {
"type": "thinking_turns",
"value": 2
}
},
{
"type": "clear_tool_uses_20250919",
"trigger": {
"type": "input_tokens",
"value": 50000
},
"keep": {
"type": "tool_uses",
"value": 5
}
}
]
}
)clear_tool_inputs | false | Steuert, ob die Tool-Call-Parameter zusammen mit den Tool-Ergebnissen gelöscht werden. Standardmäßig werden nur die Tool-Ergebnisse gelöscht, während Claudes ursprüngliche Tool-Aufrufe sichtbar bleiben. |
response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[...],
thinking={
"type": "enabled",
"budget_tokens": 10000
},
tools=[...],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {
"type": "thinking_turns",
"value": 2
}
},
{
"type": "clear_tool_uses_20250919",
"trigger": {
"type": "input_tokens",
"value": 50000
},
"keep": {
"type": "tool_uses",
"value": 5
}
}
]
}
)clear_tool_inputs | false | Steuert, ob die Tool-Call-Parameter zusammen mit den Tool-Ergebnissen gelöscht werden. Standardmäßig werden nur die Tool-Ergebnisse gelöscht, während Claudes ursprüngliche Tool-Aufrufe sichtbar bleiben. |
curl https://api.anthropic.com/v1/messages/count_tokens \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "anthropic-beta: context-management-2025-06-27" \
--data '{
"model": "claude-sonnet-4-5",
"messages": [
{
"role": "user",
"content": "Continue our conversation..."
}
],
"tools": [...],
"context_management": {
"edits": [
{
"type": "clear_tool_uses_20250919",
"trigger": {
"type": "input_tokens",
"value": 30000
},
"keep": {
"type": "tool_uses",
"value": 5
}
}
]
}
}'response = client.beta.messages.create(
model="claude-sonnet-4-5",
max_tokens=4096,
messages=[...],
tools=[
{
"type": "memory_20250818",
"name": "memory"
},
# Your other tools
],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{"type": "clear_tool_uses_20250919"}
]
}
)import anthropic
client = anthropic.Anthropic()
runner = client.beta.messages.tool_runner(
model="claude-sonnet-4-5",
max_tokens=4096,
tools=[...],
messages=[
{
"role": "user",
"content": "Analyze all the files in this directory and write a summary report."
}
],
compaction_control={
"enabled": True,
"context_token_threshold": 100000
}
)
for message in runner:
print(f"Tokens used: {message.usage.input_tokens}")
final = runner.until_done()response = client.beta.messages.create(
model="claude-sonnet-4-5",
max_tokens=4096,
messages=[...],
tools=[
{
"type": "memory_20250818",
"name": "memory"
},
# Your other tools
],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{"type": "clear_tool_uses_20250919"}
]
}
)import anthropic
client = anthropic.Anthropic()
runner = client.beta.messages.tool_runner(
model="claude-sonnet-4-5",
max_tokens=4096,
tools=[...],
messages=[
{
"role": "user",
"content": "Analyze all the files in this directory and write a summary report."
}
],
compaction_control={
"enabled": True,
"context_token_threshold": 100000
}
)
for message in runner:
print(f"Tokens used: {message.usage.input_tokens}")
final = runner.until_done()