Kontextbearbeitung



Überblick

„Context editing" (Kontextbearbeitung) ermöglicht es dir, bestimmte Inhalte selektiv aus dem Gesprächsverlauf zu löschen, während 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 Grenznutzen, und irrelevante Inhalte beeinträchtigen den Fokus des Modells. Kontextbearbeitung gibt dir feingranulare Laufzeitkontrolle über diese Kuratierung. Für die allgemeineren Prinzipien hinter dem Kontextmanagement siehe Effective context engineering. Diese Seite behandelt:

• Löschen von Tool-Ergebnissen – Am besten geeignet für agentische Workflows mit intensiver Tool-Nutzung, bei denen alte Tool-Ergebnisse nicht mehr benötigt werden
• Löschen von Thinking-Blöcken – Zur Verwaltung von Thinking-Blöcken bei Verwendung von erweitertem Denken, mit Optionen zum Beibehalten aktueller Thinking-Blöcke für Kontextkontinuität
• Clientseitige SDK-Kompaktierung – Eine SDK-basierte Alternative für zusammenfassungsbasiertes Kontextmanagement (serverseitige Kompaktierung wird im Allgemeinen bevorzugt)



Serverseitige Strategien



Löschen von Tool-Ergebnissen

Die Strategie clear_tool_uses_20250919 löscht Tool-Ergebnisse, wenn der Gesprächskontext über deinen konfigurierten Schwellenwert hinauswächst. 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.

Bei Aktivierung löscht die API automatisch die ältesten Tool-Ergebnisse in chronologischer Reihenfolge. Die API ersetzt jedes gelöschte Ergebnis durch Platzhaltertext, damit Claude weiß, dass es entfernt wurde. Standardmäßig werden nur Tool-Ergebnisse gelöscht. Du kannst optional sowohl Tool-Ergebnisse als auch Tool-Aufrufe (die Tool-Use-Parameter) löschen, indem du clear_tool_inputs auf true setzt.



Löschen von Thinking-Blöcken

Die Strategie clear_thinking_20251015 verwaltet thinking-Blöcke in Gesprächen, wenn erweitertes Denken aktiviert ist. Diese Strategie gibt dir Kontrolle über die Beibehaltung von Thinking-Blöcken: Du kannst wählen, mehr Thinking-Blöcke beizubehalten, um die Kontinuität des Denkprozesses zu wahren, oder sie aggressiver zu löschen, um Platz im Kontext zu sparen.

Ein Assistant-Gesprächsturn kann mehrere Content-Blöcke enthalten (zum Beispiel bei der Verwendung von Tools) und mehrere Thinking-Blöcke (zum Beispiel bei interleaved thinking).



Kontextbearbeitung erfolgt serverseitig

Kontextbearbeitung wird serverseitig angewendet, bevor der Prompt Claude erreicht. Deine Client-Anwendung behält den vollständigen, unveränderten Gesprächsverlauf bei. Du musst deinen Client-Zustand nicht mit der bearbeiteten Version synchronisieren. Verwalte deinen vollständigen Gesprächsverlauf weiterhin lokal wie gewohnt.



Kontextbearbeitung und Prompt-Caching

Die Interaktion der Kontextbearbeitung mit Prompt-Caching variiert je nach Strategie:

• Löschen von Tool-Ergebnissen: Invalidiert gecachte Prompt-Präfixe, wenn Inhalte gelöscht werden. Um dies zu berücksichtigen, lösche genügend Token, damit sich die Cache-Invalidierung lohnt. Verwende den Parameter clear_at_least, um sicherzustellen, dass jedes Mal eine Mindestanzahl von Token gelöscht wird. Du zahlst Cache-Schreibkosten jedes Mal, wenn Inhalte gelöscht werden, aber nachfolgende Anfragen können das neu gecachte Präfix wiederverwenden.

• Löschen von Thinking-Blöcken: Wenn Thinking-Blöcke im Kontext behalten (nicht gelöscht) werden, bleibt der Prompt-Cache erhalten, was Cache-Treffer ermöglicht und die Kosten für Input-Token reduziert. Wenn Thinking-Blöcke gelöscht werden, wird der Cache an der Stelle invalidiert, an der das Löschen erfolgt. Konfiguriere den Parameter keep basierend darauf, ob du Cache-Performance oder Verfügbarkeit des Kontextfensters priorisieren möchtest.



Unterstützte Modelle

Kontextbearbeitung ist auf allen unterstützten Claude-Modellen verfügbar.



Verwendung des Löschens von Tool-Ergebnissen

Der einfachste Weg, das Löschen von Tool-Ergebnissen zu aktivieren, besteht darin, nur den Strategietyp anzugeben. Alle anderen Konfigurationsoptionen verwenden ihre Standardwerte:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)



Erweiterte Konfiguration

Du kannst das Verhalten beim Löschen von Tool-Ergebnissen mit zusätzlichen Parametern anpassen:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # Löse das Leeren aus, wenn der Schwellenwert überschritten wird
                "trigger": {"type": "input_tokens", "value": 30000},
                # Anzahl der Tool-Nutzungen, die nach dem Leeren behalten werden
                "keep": {"type": "tool_uses", "value": 3},
                # Optional: Lösche mindestens so viele Token
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Schließe diese Tools vom Leeren aus
                "exclude_tools": ["web_search"],
            }
        ]
    },
)



Verwendung des Löschens von Thinking-Blöcken

Aktiviere das Löschen von Thinking-Blöcken, um Kontext und Prompt-Caching effektiv zu verwalten, wenn erweitertes Denken aktiviert ist:

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
    thinking={"type": "enabled", "budget_tokens": 10000},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)



Konfigurationsoptionen für das Löschen von Thinking-Blöcken

Die Strategie clear_thinking_20251015 unterstützt die folgende Konfiguration:

Beispielkonfigurationen:

Thinking-Blöcke der letzten 3 Assistant-Turns behalten:

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

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

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



Strategien kombinieren

Du kannst sowohl das Löschen von Thinking-Blöcken als auch das Löschen von Tool-Ergebnissen zusammen verwenden:

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    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},
            },
        ]
    },
)



Konfigurationsoptionen für das Löschen von Tool-Ergebnissen



Kontextbearbeitungs-Antwort

Du kannst über das Antwortfeld context_management sehen, welche Kontextbearbeitungen auf deine Anfrage angewendet wurden, zusammen mit hilfreichen Statistiken über die gelöschten Inhalte und 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
      }
    ]
  }
}

Bei Streaming-Antworten werden die Kontextbearbeitungen im abschließenden message_delta-Event 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 Token-Zählungs-Endpunkt unterstützt Kontextmanagement, sodass du vorab sehen kannst, wie viele Token dein Prompt nach Anwendung der Kontextbearbeitung verwenden wird.

response = client.beta.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    tools=[...],  # Your tool definitions
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management['original_input_tokens']}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management['original_input_tokens'] - response.input_tokens} tokens"
)

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

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



Verwendung mit dem Memory-Tool

Kontextbearbeitung kann mit dem Memory-Tool kombiniert werden. Wenn sich dein Gesprächskontext dem konfigurierten Lösch-Schwellenwert nähert, erhält Claude eine automatische Warnung, 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 dir:

• Wichtigen Kontext bewahren: Claude kann wesentliche Informationen aus Tool-Ergebnissen in Memory-Dateien schreiben, bevor diese Ergebnisse gelöscht werden
• Langlaufende Workflows aufrechterhalten: Ermögliche agentische Workflows, die sonst die Kontextlimits überschreiten würden, indem Informationen in persistenten Speicher ausgelagert werden
• Informationen bei Bedarf abrufen: Claude kann zuvor gelöschte Informationen bei Bedarf aus Memory-Dateien nachschlagen, anstatt alles im aktiven Kontextfenster zu behalten

Zum Beispiel kann Claude in einem Dateibearbeitungs-Workflow, in dem viele Operationen durchgeführt werden, abgeschlossene Änderungen in Memory-Dateien zusammenfassen, während der Kontext wächst. Wenn Tool-Ergebnisse gelöscht werden, behält Claude über sein Memory-System Zugriff auf diese Informationen und kann effektiv weiterarbeiten.

Um beide Features zusammen zu verwenden, aktiviere sie in deiner API-Anfrage:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[...],
    tools=[
        {"type": "memory_20250818", "name": "memory"},
        # Deine anderen Tools
    ],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

Die vollständige Memory-Tool-Referenz einschließlich Befehlen und Beispielen findest du unter Memory-Tool.



Clientseitige Kompaktierung (SDK)

„Compaction" (Kompaktierung) ist ein SDK-Feature, das 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 Kompaktierung Claude an, den Gesprächsverlauf zusammenzufassen, und ersetzt dann den vollständigen Verlauf durch diese Zusammenfassung. Dies ermöglicht es Claude, an langlaufenden Aufgaben weiterzuarbeiten, die sonst das Kontextfenster überschreiten würden.



Wie Kompaktierung funktioniert

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

1. Schwellenwertprüfung: Das SDK berechnet die Gesamt-Token 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 User-Turn eingefügt, und Claude generiert eine strukturierte Zusammenfassung, die in <summary></summary>-Tags eingeschlossen ist.
3. Kontextersetzung: 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.



Kompaktierung verwenden

Füge compaction_control zu deinem tool_runner-Aufruf hinzu, um automatische Zusammenfassung zu aktivieren, wenn die Token-Nutzung den Schwellenwert überschreitet.



Was während der Kompaktierung passiert

Während das Gespräch wächst, sammelt sich der Nachrichtenverlauf an:

Vor der Kompaktierung (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 die Token den Schwellenwert überschreiten, fügt das SDK eine Zusammenfassungsanfrage ein und Claude generiert eine Zusammenfassung. Der gesamte Verlauf wird dann ersetzt:

Nach der Kompaktierung (zurück auf ~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 arbeitet von dieser Zusammenfassung aus weiter, als wäre sie der ursprüngliche Gesprächsverlauf.



Konfigurationsoptionen



Einen Token-Schwellenwert wählen

Der Schwellenwert bestimmt, wann Kompaktierung erfolgt. Ein niedrigerer Schwellenwert bedeutet häufigere Kompaktierungen mit kleineren Kontextfenstern. Ein höherer Schwellenwert erlaubt 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}

# Seltenere Komprimierung, wenn du mehr Kontext benötigst
compaction_control = {"enabled": True, "context_token_threshold": 150000}



Ein anderes Modell für Zusammenfassungen verwenden

Du kannst ein schnelleres oder günstigeres Modell zum Generieren von Zusammenfassungen verwenden:

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5",
}



Benutzerdefinierte Zusammenfassungs-Prompts

Du kannst einen benutzerdefinierten Prompt für domänenspezifische Anforderungen bereitstellen. Dein Prompt sollte Claude anweisen, seine Zusammenfassung in <summary></summary>-Tags einzuschließen.

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



Standard-Zusammenfassungs-Prompt

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

1. Aufgabenübersicht: Die Kernanfrage des Nutzers, Erfolgskriterien und Einschränkungen.
2. Aktueller Stand: Was abgeschlossen wurde, geänderte Dateien und erstellte Artefakte.
3. Wichtige Erkenntnisse: Technische Einschränkungen, getroffene Entscheidungen, behobene Fehler und gescheiterte Ansätze.
4. Nächste Schritte: Erforderliche spezifische Aktionen, Blocker und Prioritätsreihenfolge.
5. Zu bewahrender Kontext: Nutzerprä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, wodurch die Kompaktierung zum falschen Zeitpunkt ausgelöst wird.

Zum Beispiel könnte die API-Antwort nach einer Websuchoperation Folgendes anzeigen:

{
  "usage": {
    "input_tokens": 63000,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

Das SDK berechnet die Gesamtnutzung als 63.000 + 0 + 270.000 + 1.400 = 334.400 Token. Der Wert cache_read_input_tokens enthält jedoch akkumulierte Lesevorgänge aus mehreren internen API-Aufrufen, die vom serverseitigen Tool durchgeführt wurden, nicht deinen tatsächlichen Gesprächskontext. Deine tatsächliche Kontextlänge könnte nur die 63.000 input_tokens betragen, aber das SDK sieht 334k und löst die Kompaktierung vorzeitig aus.

Workarounds:

• Verwende den Token-Zählungs-Endpunkt, um die genaue Kontextlänge zu erhalten
• Vermeide Kompaktierung bei intensiver Nutzung serverseitiger Tools



Tool-Use-Sonderfälle

Wenn das SDK die Kompaktierung auslöst, während eine Tool-Use-Antwort aussteht, entfernt es den Tool-Use-Block aus dem Nachrichtenverlauf, bevor die Zusammenfassung generiert wird. Claude wird den Tool-Aufruf nach dem Fortsetzen von der Zusammenfassung aus erneut ausgeben, falls er noch benötigt wird.



Kompaktierung überwachen

Zu verstehen, wann Kompaktierung ausgelöst wird, hilft dir, Schwellenwerte abzustimmen und das erwartete Verhalten zu überprüfen.



Wann Kompaktierung verwendet werden sollte

Gute Anwendungsfälle:

• Langlaufende Agent-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 des Gesprächs bestehen bleiben

Weniger ideale Anwendungsfälle:

• Aufgaben, die präzises Erinnern an frühe Gesprächsdetails erfordern
• Workflows, die serverseitige Tools intensiv nutzen
• Aufgaben, die einen exakten Zustand über viele Variablen hinweg beibehalten müssen