Kontextbearbeitung

Überblick

„Context editing“ (Kontextbearbeitung) ermöglicht es dir, gezielt bestimmte Inhalte aus dem Gesprächsverlauf zu löschen, während dieser wächst. Über die Kostenoptimierung und das Einhalten von Limits hinaus geht es dabei darum, aktiv zu kuratieren, was Claude sieht: Kontext ist eine endliche Ressource mit abnehmendem Grenznutzen, und irrelevante Inhalte verschlechtern den Fokus des Modells. Kontextbearbeitung gibt dir eine feingranulare Laufzeitkontrolle über diese Kuratierung. Die übergeordneten Prinzipien hinter dem Kontextmanagement findest du unter Effective context engineering. Diese Seite behandelt:

• Löschen von Tool-Ergebnissen – Am besten geeignet für agentische Workflows mit intensiver „tool use“ (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 „extended thinking“ (erweitertem Nachdenken), mit Optionen zum Beibehalten des jüngsten Nachdenkens für Kontextkontinuität
• Clientseitige SDK-Komprimierung – Eine SDK-basierte Alternative für zusammenfassungsbasiertes Kontextmanagement (serverseitige Komprimierung 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 hinaus wä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, der Claude anzeigt, dass es entfernt wurde. Standardmäßig werden nur Tool-Ergebnisse gelöscht. Optional kannst du 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 Gesprächen, wenn erweitertes Nachdenken aktiviert ist. Diese Strategie gibt dir Kontrolle über die Beibehaltung des Nachdenkens: Du kannst wählen, mehr Thinking-Blöcke zu behalten, um die Kontinuität der Argumentation zu wahren, oder sie aggressiver zu löschen, um Kontextplatz zu sparen.

Ein Gesprächszug des Assistenten kann mehrere Inhaltsblöcke (zum Beispiel bei der Verwendung von Tools) und mehrere Thinking-Blöcke (zum Beispiel bei verschachteltem Nachdenken) enthalten.

Kontextbearbeitung erfolgt serverseitig

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

Bei Claude Fable 5.1, Claude Opus 5.5 und Claude Sonnet 5.5 macht das serverseitige Kontextmanagement Thinking-Blöcke niemals ungültig. Clientseitige Bearbeitungen früherer Turns können die Thinking-Blöcke in jedem späteren Assistant-Turn ungültig machen. Bei neuen Konten, die am oder nach dem 31. August 2026 erstellt wurden, wird eine Anfrage, die einen ungültig gemachten Block erneut sendet, abgelehnt, es sei denn, du entscheidest dich dafür, ihn zu verwerfen. Siehe Das Präfix unverändert lassen.

Kontextbearbeitung und Prompt-Caching

Die Wechselwirkung der Kontextbearbeitung mit „prompt caching“ (Prompt-Caching) variiert je nach Strategie:

• Löschen von Tool-Ergebnissen: Macht zwischengespeicherte Prompt-Präfixe ungültig, 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 an Token gelöscht wird. Dir entstehen jedes Mal Cache-Schreibkosten, wenn Inhalte gelöscht werden, aber nachfolgende Anfragen können das neu zwischengespeicherte 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 Eingabe-Token reduziert. Wenn Thinking-Blöcke gelöscht werden, wird der Cache an der Stelle ungültig, an der das Löschen erfolgt. Konfiguriere den Parameter keep danach, ob du die Cache-Leistung oder die Verfügbarkeit des Kontextfensters priorisieren möchtest.

Unterstützte Modelle

Kontextbearbeitung ist für alle unterstützten Claude-Modelle 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-5-5",
    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-5-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},
    ],
    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-Aufrufe, die nach dem Leeren erhalten bleiben
                "keep": {"type": "tool_uses", "value": 3},
                # Optional: Leere 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 Nachdenken aktiviert ist:

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    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 Assistentenzüge behalten:

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    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-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)

Strategien kombinieren

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

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    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

Antwort der Kontextbearbeitung

Über das Antwortfeld context_management kannst du sehen, welche Kontextbearbeitungen auf deine Anfrage angewendet wurden, zusammen mit hilfreichen Statistiken über die gelöschten Inhalte und Eingabe-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 Endpunkt zur Token-Zählung 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-5-5",
    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 Gesprächskontext dem konfigurierten Löschschwellenwert nähert, erhält Claude eine automatische Warnung, wichtige Informationen zu sichern. 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
• 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 in Memory-Dateien nachschlagen, anstatt alles im aktiven Kontextfenster zu behalten

In einem Dateibearbeitungs-Workflow, in dem Claude viele Operationen durchführt, kann Claude beispielsweise 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 Funktionen zusammen zu verwenden, aktiviere sie in deiner API-Anfrage:

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

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

Clientseitige Komprimierung (SDK)

„Compaction“ (Komprimierung) ist eine SDK-Funktion, die den Gesprächskontext automatisch verwaltet, indem sie Zusammenfassungen erzeugt, 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 andernfalls das „context window“ (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 Gesamtzahl der Token als input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens (siehe Prompt-Caching für die Cache-Token-Felder).
2. Erzeugung der Zusammenfassung: Wenn der Schwellenwert überschritten wird, wird ein Zusammenfassungs-Prompt als Benutzerzug eingefügt, und Claude erzeugt eine strukturierte Zusammenfassung, die in <summary></summary>-Tags eingeschlossen ist.
3. Kontextersetzung: Das SDK extrahiert die Zusammenfassung und ersetzt den gesamten Nachrichtenverlauf durch sie.
4. Fortsetzung: Das Gespräch wird von der Zusammenfassung aus fortgesetzt, wobei Claude dort weitermacht, wo es aufgehört hat.

Komprimierung 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 Komprimierung geschieht

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

Vor der Komprimierung (nahe 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 erzeugt eine Zusammenfassung. Der gesamte Verlauf wird dann ersetzt:

Nach der Komprimierung (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 die Komprimierung erfolgt. Ein niedrigerer Schwellenwert bedeutet häufigere Komprimierungen 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 zur Erzeugung 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überblick: Die Kernanfrage des Benutzers, Erfolgskriterien und Einschränkungen.
2. Aktueller Stand: Was abgeschlossen wurde, geänderte Dateien und erzeugte Artefakte.
3. Wichtige Erkenntnisse: Technische Einschränkungen, getroffene Entscheidungen, behobene Fehler und gescheiterte Ansätze.
4. Nächste Schritte: Konkret erforderliche Aktionen, Blocker und Prioritätsreihenfolge.
5. Zu bewahrender Kontext: Benutzerpräferenzen, domänenspezifische Details und eingegangene Verpflichtungen.

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

You have been working on the task described above but have not yet completed it. Write a continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary. Your summary should be structured, concise, and actionable. Include:

1. Task Overview
The user's core request and success criteria
Any clarifications or constraints they specified

2. Current State
What has been completed so far
Files created, modified, or analyzed (with paths if relevant)
Key outputs or artifacts produced

3. Important Discoveries
Technical constraints or requirements uncovered
Decisions made and their rationale
Errors encountered and how they were resolved
What approaches were tried that didn't work (and why)

4. Next Steps
Specific actions needed to complete the task
Any blockers or open questions to resolve
Priority order if multiple steps remain

5. Context to Preserve
User preferences or style requirements
Domain-specific details that aren't obvious
Any promises made to the user

Be concise but complete—err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.

Wrap your summary in <summary></summary> tags.

Einschränkungen

Serverseitige Tools

Bei der Verwendung serverseitiger Tools kann das SDK die Token-Nutzung falsch berechnen, wodurch die Komprimierung zum falschen Zeitpunkt ausgelöst wird.

Nach einer Websuche-Operation könnte die API-Antwort beispielsweise 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 des serverseitigen Tools, nicht deinen tatsächlichen Gesprächskontext. Deine reale Kontextlänge beträgt möglicherweise nur die 63.000 input_tokens, aber das SDK sieht 334k und löst die Komprimierung vorzeitig aus.

Workarounds:

• Verwende den Endpunkt zur Token-Zählung, um die genaue Kontextlänge zu erhalten
• Vermeide Komprimierung, wenn du serverseitige Tools intensiv nutzt

Sonderfälle bei der Tool-Nutzung

Wenn das SDK die Komprimierung auslöst, während eine Tool-Nutzungsantwort aussteht, entfernt es den Tool-Nutzungsblock aus dem Nachrichtenverlauf, bevor es die Zusammenfassung erzeugt. Claude wird den Tool-Aufruf nach der Fortsetzung von der Zusammenfassung aus erneut ausführen, falls er noch benötigt wird.

Komprimierung überwachen

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

Wann Komprimierung verwendet werden sollte

Gute Anwendungsfälle:

• Lang laufende Agentenaufgaben, 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 eine präzise Erinnerung an frühe Gesprächsdetails erfordern
• Workflows, die serverseitige Tools intensiv nutzen
• Aufgaben, die einen exakten Zustand über viele Variablen hinweg aufrechterhalten müssen

Nächste Schritte