Kontextbearbeitung

Übersicht

Die Kontextbearbeitung ermöglicht es Ihnen, bestimmte Inhalte aus dem Gesprächsverlauf selektiv zu löschen, wenn dieser wächst. Über die Optimierung von Kosten und das Einhalten von Limits hinaus geht es darum, aktiv zu kuratieren, was Claude sieht: Kontext ist eine endliche Ressource mit abnehmendem Ertrag, und irrelevante Inhalte beeinträchtigen den Modellfokus. Die Kontextbearbeitung gibt Ihnen eine feinkörnige Laufzeitkontrolle über diese Kuratierung. Für die übergeordneten Prinzipien hinter dem Kontextmanagement siehe Effective context engineering. Diese Seite behandelt:

• Tool-Ergebnis-Löschung - Am besten für agentische Workflows mit intensiver Tool-Nutzung, bei denen alte Tool-Ergebnisse nicht mehr benötigt werden
• Thinking-Block-Löschung - Zur Verwaltung von Thinking-Blöcken bei der Verwendung von erweitertem Denken, mit Optionen zur Beibehaltung des jüngsten Denkens für Kontextkontinuität
• Clientseitige SDK-Komprimierung - Eine SDK-basierte Alternative für zusammenfassungsbasiertes Kontextmanagement (serverseitige Komprimierung wird generell bevorzugt)

Serverseitige Strategien

Tool-Ergebnis-Löschung

Die Strategie clear_tool_uses_20250919 löscht Tool-Ergebnisse, wenn der Gesprächskontext Ihren konfigurierten Schwellenwert überschreitet. Dies ist besonders nützlich für agentische Workflows mit intensiver Tool-Nutzung. Ältere Tool-Ergebnisse (wie Dateiinhalte oder Suchergebnisse) werden nicht mehr benötigt, sobald Claude sie verarbeitet hat.

Wenn aktiviert, löscht die API automatisch die ältesten Tool-Ergebnisse in chronologischer Reihenfolge. Jedes gelöschte Ergebnis wird durch Platzhaltertext ersetzt, damit Claude weiß, dass es entfernt wurde. Standardmäßig werden nur Tool-Ergebnisse gelöscht. Sie können optional sowohl Tool-Ergebnisse als auch Tool-Aufrufe (die Tool-Verwendungsparameter) löschen, indem Sie clear_tool_inputs auf true setzen.

Thinking-Block-Löschung

Die Strategie clear_thinking_20251015 verwaltet thinking-Blöcke in Gesprächen, wenn erweitertes Denken aktiviert ist. Diese Strategie gibt Ihnen Kontrolle über die Thinking-Beibehaltung: Sie können wählen, mehr Thinking-Blöcke zu behalten, um die Denkkontinuität aufrechtzuerhalten, oder sie aggressiver zu löschen, um Kontextraum zu sparen.

Ein Assistenten-Gesprächsturn kann mehrere Inhaltsblöcke enthalten (z. B. bei der Verwendung von Tools) und mehrere Thinking-Blöcke (z. B. mit verschachteltem Denken).

Kontextbearbeitung erfolgt serverseitig

Die Kontextbearbeitung wird serverseitig angewendet, bevor der Prompt Claude erreicht. Ihre Client-Anwendung behält den vollständigen, unveränderten Gesprächsverlauf. 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 dem Prompt-Caching variiert je nach Strategie:

• Tool-Ergebnis-Löschung: Invalidiert zwischengespeicherte Prompt-Präfixe, wenn Inhalte gelöscht werden. Um dies zu berücksichtigen, löschen Sie genug Token, 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. Jedes Mal, wenn Inhalte gelöscht werden, entstehen Cache-Schreibkosten, aber nachfolgende Anfragen können das neu zwischengespeicherte Präfix wiederverwenden.

• Thinking-Block-Löschung: Wenn Thinking-Blöcke im Kontext beibehalten werden (nicht gelöscht), bleibt der Prompt-Cache erhalten, was Cache-Treffer ermöglicht und die Eingabe-Token-Kosten reduziert. Wenn Thinking-Blöcke gelöscht werden, wird der Cache an dem Punkt invalidiert, an dem die Löschung erfolgt. Konfigurieren Sie den Parameter keep basierend darauf, ob Sie die Cache-Leistung oder die Verfügbarkeit des Kontextfensters priorisieren möchten.

Unterstützte Modelle

Die Kontextbearbeitung ist verfügbar für:

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

Verwendung der Tool-Ergebnis-Löschung

Die einfachste Möglichkeit, die Tool-Ergebnis-Löschung zu aktivieren, besteht darin, nur den Strategietyp anzugeben. Alle anderen Konfigurationsoptionen verwenden ihre Standardwerte:

Erweiterte Konfiguration

Sie können das Verhalten der Tool-Ergebnis-Löschung mit zusätzlichen Parametern anpassen:

Verwendung der Thinking-Block-Löschung

Aktivieren Sie die Thinking-Block-Löschung, um den Kontext und das Prompt-Caching effektiv zu verwalten, wenn erweitertes Denken aktiviert ist:

Konfigurationsoptionen für die Thinking-Block-Löschung

Die Strategie clear_thinking_20251015 unterstützt die folgende Konfiguration:

Beispielkonfigurationen:

Thinking-Blöcke aus den letzten 3 Assistenten-Turns beibehalten:

{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

Alle Thinking-Blöcke beibehalten (maximiert Cache-Treffer):

{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Strategien kombinieren

Sie können sowohl Thinking-Block-Löschung als auch Tool-Ergebnis-Löschung zusammen verwenden:

Konfigurationsoptionen für die Tool-Ergebnis-Löschung

Antwort der Kontextbearbeitung

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 gelöschten Eingabe-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 abschließenden message_delta-Ereignis enthalten sein:

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

Token-Zählung

Der Endpunkt zur Token-Zählung unterstützt das Kontextmanagement und ermöglicht es Ihnen, eine Vorschau zu sehen, wie viele Token Ihr Prompt nach der Anwendung der Kontextbearbeitung verwenden wird.

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

Die Antwort zeigt sowohl die endgültige Token-Anzahl nach der Anwendung des Kontextmanagements (input_tokens) als auch die ursprüngliche Token-Anzahl vor jeglicher Löschung (original_input_tokens).

Verwendung mit dem Memory-Tool

Die Kontextbearbeitung kann mit dem Memory-Tool kombiniert werden. Wenn Ihr Gesprächskontext den konfigurierten Löschschwellenwert nähert, erhält Claude eine automatische Warnung, wichtige Informationen zu bewahren. Dies ermöglicht es Claude, Tool-Ergebnisse oder Kontext in seinen Speicherdateien zu speichern, bevor sie aus dem Gesprächsverlauf gelöscht werden.

Diese Kombination ermöglicht Ihnen:

• Wichtigen Kontext bewahren: Claude kann wesentliche Informationen aus Tool-Ergebnissen in Speicherdateien schreiben, bevor diese Ergebnisse gelöscht werden
• Lang laufende Workflows aufrechterhalten: Agentische Workflows ermöglichen, die sonst die Kontextgrenzen überschreiten würden, indem Informationen in persistenten Speicher ausgelagert werden
• Informationen bei Bedarf abrufen: Claude kann zuvor gelöschte Informationen aus Speicherdateien nachschlagen, wenn sie benötigt werden, anstatt alles im aktiven Kontextfenster zu behalten

Zum Beispiel kann Claude in einem Dateibearbeitungs-Workflow, bei dem Claude viele Operationen durchführt, abgeschlossene Änderungen in Speicherdateien zusammenfassen, wenn der Kontext wächst. Wenn Tool-Ergebnisse gelöscht werden, behält Claude über sein Speichersystem Zugriff auf diese Informationen und kann weiterhin effektiv arbeiten.

Um beide Funktionen zusammen zu verwenden, aktivieren Sie sie in Ihrer API-Anfrage:

Clientseitige Komprimierung (SDK)

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 lang laufenden Aufgaben weiterzuarbeiten, die sonst das Kontextfenster überschreiten würden.

Wie Komprimierung funktioniert

Wenn Komprimierung aktiviert ist, überwacht das SDK die Token-Nutzung nach jeder Modellantwort:

1. Schwellenwertprüfung: Das SDK berechnet die Gesamttoken als input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens.
2. Zusammenfassungsgenerierung: Wenn der Schwellenwert überschritten wird, wird ein Zusammenfassungs-Prompt als Benutzer-Turn eingefügt, und Claude generiert eine strukturierte Zusammenfassung, die in <summary></summary>-Tags eingeschlossen ist.
3. Kontextersatz: Das SDK extrahiert die Zusammenfassung und ersetzt den gesamten Nachrichtenverlauf damit.
4. Fortsetzung: Das Gespräch wird von der Zusammenfassung aus fortgesetzt, wobei Claude dort weitermacht, wo es aufgehört hat.

Komprimierung verwenden

Fügen Sie compaction_control zu Ihrem tool_runner-Aufruf hinzu:

Was während der Komprimierung passiert

Wenn das Gespräch wächst, akkumuliert sich der Nachrichtenverlauf:

Vor der Komprimierung (nähert sich 100.000 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 weitere Austausche wie dieser ...
]

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 auf ~2-3.000 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 arbeitet von dieser Zusammenfassung aus weiter, als wäre es der ursprüngliche Gesprächsverlauf.

Konfigurationsoptionen

Einen Token-Schwellenwert wählen

Der Schwellenwert bestimmt, wann die Komprimierung erfolgt. Ein niedrigerer Schwellenwert bedeutet häufigere Komprimierungen mit kleineren Kontextfenstern. Ein höherer Schwellenwert ermöglicht mehr Kontext, birgt aber das Risiko, Limits zu erreichen.

# Häufigere Komprimierung für speicherbeschränkte 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}

Ein anderes Modell für Zusammenfassungen verwenden

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",
}

Benutzerdefinierte Zusammenfassungs-Prompts

Sie können einen benutzerdefinierten Prompt für domänenspezifische Anforderungen bereitstellen. Ihr Prompt sollte Claude anweisen, seine Zusammenfassung in <summary></summary>-Tags einzuschließen.

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """Fassen Sie die bisher durchgeführten Recherchen zusammen, einschließlich:
- Konsultierte Quellen und wichtige Erkenntnisse
- Beantwortete Fragen und verbleibende Unbekannte
- Empfohlene nächste Schritte

Schließen Sie Ihre Zusammenfassung in <summary></summary>-Tags ein.""",
}

Standard-Zusammenfassungsprompt

Der integrierte Zusammenfassungsprompt weist Claude an, eine strukturierte Fortsetzungszusammenfassung zu erstellen, die Folgendes enthält:

1. Aufgabenübersicht: Die Kernanfrage des Benutzers, Erfolgskriterien und Einschränkungen.
2. Aktueller Stand: Was abgeschlossen wurde, welche Dateien geändert und welche Artefakte erstellt wurden.
3. Wichtige Erkenntnisse: Technische Einschränkungen, getroffene Entscheidungen, behobene Fehler und fehlgeschlagene Ansätze.
4. Nächste Schritte: Erforderliche spezifische Maßnahmen, Hindernisse und Prioritätsreihenfolge.
5. Zu bewahrender Kontext: Benutzerpräferenzen, domänenspezifische Details und gemachte Zusagen.

Diese Struktur ermöglicht es Claude, die Arbeit effizient fortzusetzen, ohne wichtigen Kontext zu verlieren oder Fehler zu wiederholen.

Einschränkungen

Serverseitige Tools

Bei der Verwendung serverseitiger Tools kann das SDK die Token-Nutzung falsch berechnen, was dazu führt, dass die Komprimierung zum falschen Zeitpunkt ausgelöst wird.

Nach einer Web-Suchanfrage könnte die API-Antwort beispielsweise so 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 Token. Der Wert cache_read_input_tokens enthält jedoch akkumulierte Lesevorgänge aus mehreren internen API-Aufrufen des serverseitigen Tools, nicht Ihren tatsächlichen Konversationskontext. Ihre tatsächliche Kontextlänge könnte nur die 63.000 input_tokens betragen, aber das SDK sieht 333.000 und löst die Komprimierung vorzeitig aus.

Workarounds:

• Verwenden Sie den Token-Zählung-Endpunkt, um die genaue Kontextlänge zu ermitteln
• Vermeiden Sie die Komprimierung bei umfangreicher Nutzung serverseitiger Tools

Randfälle bei der Tool-Nutzung

Wenn die Komprimierung ausgelöst wird, während eine Tool-Use-Antwort aussteht, 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 erneut ausgeben, falls er noch benötigt wird.

Komprimierung überwachen

Aktivieren Sie die Protokollierung, um zu verfolgen, wann eine Komprimierung stattfindet:

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: 2500

Wann Komprimierung verwendet werden sollte

Geeignete Anwendungsfälle:

• Lang laufende Agenten-Aufgaben, die viele Dateien oder Datenquellen verarbeiten
• Recherche-Workflows, die große Mengen an Informationen ansammeln
• Mehrstufige Aufgaben mit klarem, messbarem Fortschritt
• Aufgaben, die Artefakte (Dateien, Berichte) erzeugen, die außerhalb der Konversation bestehen bleiben

Weniger geeignete Anwendungsfälle:

• Aufgaben, die eine präzise Erinnerung an frühe Konversationsdetails erfordern
• Workflows, die serverseitige Tools umfangreich nutzen
• Aufgaben, die einen exakten Zustand über viele Variablen hinweg aufrechterhalten müssen