Kontextbearbeitung

Übersicht

Die Kontextbearbeitung ermöglicht es Ihnen, selektiv spezifische Inhalte aus der Gesprächshistorie zu löschen, während sie wächst. Über die Optimierung von Kosten und die Einhaltung von Grenzen hinaus geht es darum, aktiv zu kuratieren, was Claude sieht: Kontext ist eine endliche Ressource mit abnehmenden Erträgen, und irrelevante Inhalte beeinträchtigen den Fokus des Modells. Die Kontextbearbeitung gibt Ihnen eine präzise Laufzeitkontrolle über diese Kuration. Für die breiteren Prinzipien hinter der Kontextverwaltung siehe Effektive Kontextentwicklung. Diese Seite behandelt:

• Werkzeugergebnis-Löschen - Am besten für agentenbasierte Workflows mit intensiver Werkzeugnutzung, bei denen alte Werkzeugergebnisse nicht mehr benötigt werden
• Thinking-Block-Löschen - Zur Verwaltung von Thinking-Blöcken bei Verwendung von Extended Thinking, mit Optionen zum Beibehalten von aktuellem Thinking für Kontextkontinuität
• Client-seitige SDK-Komprimierung - Eine SDK-basierte Alternative für zusammenfassungsbasierte Kontextverwaltung (serverseitige Komprimierung wird allgemein bevorzugt)

Serverseitige Strategien

Werkzeugergebnis-Löschen

Die Strategie clear_tool_uses_20250919 löscht Werkzeugergebnisse, wenn der Gesprächskontext über Ihren konfigurierten Schwellenwert hinauswächst. Dies ist besonders nützlich für agentenbasierte Workflows mit intensiver Werkzeugnutzung. Ältere Werkzeugergebnisse (wie Dateiinhalte oder Suchergebnisse) werden nicht mehr benötigt, sobald Claude sie verarbeitet hat.

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

Thinking-Block-Löschen

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

Ein Assistent-Gesprächs-Turn kann mehrere Inhaltsblöcke enthalten (z. B. bei Werkzeugnutzung) und mehrere Thinking-Blöcke (z. B. mit verschachteltem Thinking).

Kontextbearbeitung erfolgt serverseitig

Die Kontextbearbeitung wird serverseitig angewendet, bevor der Prompt Claude erreicht. Ihre Client-Anwendung behält die vollständige, unmodifizierte Gesprächshistorie. Sie müssen Ihren Client-Status nicht mit der bearbeiteten Version synchronisieren. Verwalten Sie Ihre vollständige Gesprächshistorie weiterhin lokal wie gewohnt.

Kontextbearbeitung und Prompt-Caching

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

• Werkzeugergebnis-Löschen: 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. Sie entstehen Cache-Schreibkosten jedes Mal, wenn Inhalte gelöscht werden, aber nachfolgende Anfragen können das neu zwischengespeicherte Präfix wiederverwenden.

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

Unterstützte Modelle

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

Werkzeugergebnis-Löschen Verwendung

Die einfachste Möglichkeit, das Werkzeugergebnis-Löschen zu aktivieren, besteht darin, nur den Strategietyp anzugeben. Alle anderen Konfigurationsoptionen verwenden ihre Standardwerte:

Erweiterte Konfiguration

Sie können das Verhalten des Werkzeugergebnis-Löschens mit zusätzlichen Parametern anpassen:

Verwendung von Thinking-Block-Clearing

Aktivieren Sie das Clearing von Thinking-Blöcken, um den Kontext und das Prompt-Caching effektiv zu verwalten, wenn erweitertes Denken aktiviert ist:

Konfigurationsoptionen für das Clearing von Thinking-Blöcken

Die Strategie clear_thinking_20251015 unterstützt die folgende Konfiguration:

Beispielkonfigurationen:

Thinking-Blöcke aus den letzten 3 Assistent-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"
}

Kombinieren von Strategien

Sie können das Clearing von Thinking-Blöcken und das Clearing von Tool-Ergebnissen zusammen verwenden:

Konfigurationsoptionen für das Clearing von Tool-Ergebnissen

Antwort zur 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 Input-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 finalen 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 Endpunkt zur Token-Zählung unterstützt Kontextmanagement, sodass Sie eine Vorschau erhalten können, wie viele Token Ihr Prompt nach Anwendung der Kontextbearbeitung verwendet.

{
  "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 dem Clearing (original_input_tokens).

Verwendung mit dem Memory Tool

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

Diese Kombination ermöglicht es Ihnen:

• Wichtigen Kontext bewahren: Claude kann wichtige Informationen aus Tool-Ergebnissen in Memory-Dateien schreiben, bevor diese Ergebnisse gelöscht werden
• Langfristige Workflows beibehalten: Ermöglichen Sie agentenbasierte Workflows, die sonst die Kontextgrenzen überschreiten würden, indem Sie Informationen in persistenten Speicher auslagern
• Auf Anfrage auf Informationen zugreifen: Claude kann zuvor gelöschte Informationen aus Memory-Dateien nachschlagen, wenn nötig, anstatt alles im aktiven Kontextfenster zu behalten

Beispielsweise 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 Zugriff auf diese Informationen durch sein Memory-System und kann effektiv weiterarbeiten.

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

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

Client-seitige Komprimierung (SDK)

Die 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 Server-seitigen 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 Claude, an langfristigen Aufgaben zu arbeiten, die sonst das Kontextfenster überschreiten würden.

Wie die Komprimierung funktioniert

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

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 eine Zusammenfassungsaufforderung als Benutzerzug 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.

Verwendung der Komprimierung

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

Was während der Komprimierung geschieht

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

Vor der Komprimierung (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 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 zu ~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 setzt die Arbeit von dieser Zusammenfassung aus fort, als wäre es der ursprüngliche Gesprächsverlauf.

Konfigurationsoptionen

Auswahl eines Token-Schwellenwerts

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, riskiert aber, Grenzen zu erreichen.

# More frequent compaction for memory-constrained scenarios
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# Less frequent compaction when you need more context
compaction_control = {"enabled": True, "context_token_threshold": 150000}

Verwendung eines anderen Modells für Zusammenfassungen

Sie können ein schnelleres oder günstigeres Modell für die Zusammenfassungsgenerierung verwenden:

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

Benutzerdefinierte Zusammenfassungsaufforderungen

Sie können eine benutzerdefinierte Aufforderung für domänenspezifische Anforderungen bereitstellen. Ihre Aufforderung 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-Zusammenfassungsaufforderung

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

1. Aufgabenübersicht: Die Kernbitte des Benutzers, Erfolgskriterien und Einschränkungen.
2. Aktueller Status: Was abgeschlossen wurde, welche Dateien geändert wurden und welche Artefakte produziert wurden.
3. Wichtige Erkenntnisse: Technische Einschränkungen, getroffene Entscheidungen, behobene Fehler und fehlgeschlagene Ansätze.
4. Nächste Schritte: Spezifische erforderliche Maßnahmen, Blocker und Prioritätsreihenfolge.
5. Zu bewahrende Kontext: Benutzerpräferenzen, domänenspezifische Details und eingegangene Verpflichtungen.

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

Einschränkungen

Server-seitige Tools

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

Beispielsweise könnte die API-Antwort nach einer Web-Search-Operation Folgendes anzeigen:

{
  "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 cache_read_input_tokens-Wert umfasst jedoch akkumulierte Lesevorgänge aus mehreren internen API-Aufrufen, die vom Server-seitigen Tool durchgeführt werden, nicht Ihren tatsächlichen Gesprächskontext. Ihr echter Kontextlänge könnte nur die 63.000 input_tokens sein, aber das SDK sieht 333k und löst die Komprimierung vorzeitig aus.

Workarounds:

• Verwenden Sie den Token-Zählungs-Endpunkt, um die genaue Kontextlänge zu erhalten
• Vermeiden Sie Komprimierung bei umfangreicher Verwendung von Server-seitigen Tools

Tool-Use-Grenzfälle

Wenn das SDK die Komprimierung auslöst, während eine Tool-Use-Antwort ausstehend ist, entfernt es den Tool-Use-Block aus dem Nachrichtenverlauf, bevor die Zusammenfassung generiert wird. Claude gibt den Tool-Aufruf nach der Wiederaufnahme von der Zusammenfassung aus erneut aus, falls noch erforderlich.

Überwachung der Komprimierung

Das Verständnis, wann die Komprimierung ausgelöst wird, hilft Ihnen, Schwellenwerte zu optimieren und das erwartete Verhalten zu überprüfen.

Wann sollte Komprimierung verwendet werden

Gute Anwendungsfälle:

• Langfristige Agent-Aufgaben, die viele Dateien oder Datenquellen verarbeiten
• Forschungs-Workflows, die große Mengen an Informationen sammeln
• Mehrstufige Aufgaben mit klarem, messbarem Fortschritt
• Aufgaben, die Artefakte (Dateien, Berichte) produzieren, die außerhalb des Gesprächs bestehen bleiben

Weniger ideale Anwendungsfälle:

• Aufgaben, die genaue Erinnerung an frühe Gesprächsdetails erfordern
• Workflows, die Server-seitige Tools umfangreich nutzen
• Aufgaben, die genauen Status über viele Variablen hinweg beibehalten müssen