Kontextbearbeitung



Überblick

„Context editing" (Kontextbearbeitung) ermöglicht es dir, bestimmte Inhalte selektiv aus dem Konversationsverlauf zu löschen, während dieser wächst. Über die Kostenoptimierung 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 zur Laufzeit feingranulare Kontrolle ü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-Compaction – Eine SDK-basierte Alternative für zusammenfassungsbasiertes Kontextmanagement (serverseitige Compaction wird generell bevorzugt)



Serverseitige Strategien



Löschen von Tool-Ergebnissen

Die Strategie clear_tool_uses_20250919 löscht Tool-Ergebnisse, wenn der Konversationskontext ü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 einen 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-Nutzungsparameter) 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 Konversationen, 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 zu behalten, um die Kontinuität des Denkprozesses zu wahren, oder sie aggressiver zu löschen, um Platz im Kontext zu sparen.

Ein Assistant-Konversations-Turn kann mehrere Content-Blöcke enthalten (zum Beispiel bei der Verwendung von Tools) und mehrere Thinking-Blöcke (zum Beispiel mit Interleaved Thinking).



Kontextbearbeitung erfolgt serverseitig

Kontextbearbeitung wird serverseitig angewendet, bevor der Prompt Claude erreicht. Deine Client-Anwendung behält den vollständigen, unveränderten Konversationsverlauf bei. Du musst deinen Client-Zustand nicht mit der bearbeiteten Version synchronisieren. Verwalte deinen vollständigen Konversationsverlauf lokal weiterhin 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 Input-Token-Kosten 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 Löschen aus, wenn der Schwellenwert überschritten wird
                "trigger": {"type": "input_tokens", "value": 30000},
                # Anzahl der Tool-Nutzungen, die nach dem Löschen 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 Löschen 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-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    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:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "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-8",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    thinking={"type": "adaptive"},
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    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},
            },
        ]
    },
)

print(response)



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 sind die Kontextbearbeitungen im abschließenden message_delta-Event enthalten:

{
  "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 eine Vorschau darauf erhalten 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..."}],
    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 Konversationskontext 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 Konversationsverlauf 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
• Lang laufende Workflows aufrechterhalten: Ermögliche agentische Workflows, die andernfalls Kontextlimits überschreiten würden, indem Informationen in persistenten Speicher ausgelagert werden
• Bei Bedarf auf Informationen zugreifen: 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 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 ü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=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

Für die vollständige Memory-Tool-Referenz einschließlich Befehlen und Beispielen siehe Memory-Tool.



Clientseitige Compaction (SDK)

„Compaction" (Kompaktierung) ist ein SDK-Feature, das den Konversationskontext automatisch verwaltet, indem es Zusammenfassungen generiert, wenn die Token-Nutzung zu groß wird. Im Gegensatz zu serverseitigen Kontextbearbeitungsstrategien, die Inhalte löschen, weist Compaction Claude an, den Konversationsverlauf zusammenzufassen, und ersetzt dann den vollständigen Verlauf durch diese Zusammenfassung. Dies ermöglicht es Claude, an lang laufenden Aufgaben weiterzuarbeiten, die andernfalls das Kontextfenster überschreiten würden.



Wie Compaction funktioniert

Wenn Compaction 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: Die Konversation wird von der Zusammenfassung aus fortgesetzt, wobei Claude dort weitermacht, wo es aufgehört hat.



Compaction verwenden

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



Was während der Compaction passiert

Während die Konversation wächst, sammelt sich der Nachrichtenverlauf an:

Vor der Compaction (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 Compaction (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 Konversationsverlauf.



Konfigurationsoptionen



Einen Token-Schwellenwert wählen

Der Schwellenwert bestimmt, wann Compaction erfolgt. Ein niedrigerer Schwellenwert bedeutet häufigere Compactions mit kleineren Kontextfenstern. Ein höherer Schwellenwert erlaubt mehr Kontext, birgt aber das Risiko, Limits zu erreichen.



Ein anderes Modell für Zusammenfassungen verwenden

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



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.



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: Spezifische erforderliche 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 Compaction zum falschen Zeitpunkt ausgelöst wird.

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

{
  "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 Konversationskontext. Deine tatsächliche Kontextlänge könnte nur die 63.000 input_tokens betragen, aber das SDK sieht 334k und löst Compaction vorzeitig aus.

Workarounds:

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



Tool-Nutzungs-Sonderfälle

Wenn das SDK Compaction auslöst, während eine Tool-Nutzungs-Antwort aussteht, entfernt es den Tool-Nutzungs-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.



Compaction überwachen

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



Wann Compaction verwendet werden sollte

Gute Anwendungsfälle:

• Lang laufende 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 der Konversation bestehen bleiben

Weniger ideale Anwendungsfälle:

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



Nächste Schritte