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 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 Nutzen, und irrelevante Inhalte beeinträchtigen den Fokus des Modells. Kontextbearbeitung gibt dir zur Laufzeit feingranulare Kontrolle über diese Kuratierung. Für die umfassenderen Prinzipien hinter der Kontextverwaltung 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 des jüngsten Denkens für Kontextkontinuität
• Clientseitige SDK-Kompaktierung – Eine SDK-basierte Alternative für zusammenfassungsbasierte Kontextverwaltung (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 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.

Wenn aktiviert, 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-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 des Denkens: 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-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 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 trägst jedes Mal Cache-Schreibkosten, 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 werden (nicht gelöscht), 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-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",
    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 beibehalten 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-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 Assistant-Turns behalten:

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

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 Kontextverwaltung, 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-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 der Kontextverwaltung (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öschschwellenwert 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-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"}]},
)

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



Clientseitige Kompaktierung (SDK)

„Compaction" (Kompaktierung) ist ein SDK-Feature, das den Konversationskontext 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 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 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: Die Konversation 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.

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={"enabled": True, "context_token_threshold": 100000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



Was während der Kompaktierung passiert

Während die Konversation 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 Konversationsverlauf.



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.

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    # Niedrigere Werte komprimieren häufiger; erhöhe auf 150000, wenn die Aufgabe mehr Kontext benötigt
    compaction_control={"enabled": True, "context_token_threshold": 50000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



Ein anderes Modell für Zusammenfassungen verwenden

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

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,
        "model": "claude-haiku-4-5",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



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.

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    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.""",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



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 fehlgeschlagene 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 Kompaktierung 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 Kompaktierung vorzeitig aus.

Workarounds:

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



Edge Cases bei Tool-Nutzung

Wenn das SDK Kompaktierung auslöst, während eine Tool-Nutzungsantwort aussteht, entfernt es den Tool-Nutzungsblock 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 erwartetes Verhalten zu verifizieren.

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# Die Logs zeigen:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500



Wann Kompaktierung 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