Kontextbearbeitung

Übersicht

Mit der Kontextbearbeitung können Sie selektiv spezifische Inhalte aus der Gesprächshistorie löschen, während sie wächst. Dies hilft Ihnen, Kosten zu optimieren und innerhalb der Kontextfenstergrenzen zu bleiben. 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 zur Beibehaltung 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, nachdem Claude sie verarbeitet hat.

Wenn aktiviert, löscht die API automatisch die ältesten Werkzeugergebnisse in chronologischer Reihenfolge. Jedes gelöschte Ergebnis wird durch Platzhaltertext ersetzt, 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 Argumentationskontinuität zu wahren, oder sie aggressiver zu löschen, um Kontextraum zu sparen.

Ein Assistenten-Gesprächs-Turn kann mehrere Content-Blöcke enthalten (z. B. bei Verwendung von Werkzeugen) 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, unveränderte Gesprächshistorie. Sie müssen Ihren Client-Status nicht mit der bearbeiteten Version synchronisieren. Verwalten Sie weiterhin Ihre vollständige Gesprächshistorie 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 Input-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 Kontextfensterverfügbarkeit priorisieren möchten.

Unterstützte Modelle

Die Kontextbearbeitung ist verfügbar auf:

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

Werkzeugergebnis-Löschen Verwendung

Der einfachste Weg, das Werkzeugergebnis-Löschen zu aktivieren, ist, nur den Strategietyp anzugeben. Alle anderen Konfigurationsoptionen verwenden ihre Standardwerte:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Search for recent developments in AI"
            }
        ],
        "tools": [
            {
                "type": "web_search_20250305",
                "name": "web_search"
            }
        ],
        "context_management": {
            "edits": [
                {"type": "clear_tool_uses_20250919"}
            ]
        }
    }'

Erweiterte Konfiguration

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "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
            }
        ],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 3
                    },
                    "clear_at_least": {
                        "type": "input_tokens",
                        "value": 5000
                    },
                    "exclude_tools": ["web_search"]
                }
            ]
        }
    }'

Thinking-Block-Löschen Verwendung

Aktivieren Sie das Thinking-Block-Löschen, um den Kontext und das Prompt-Caching effektiv zu verwalten, wenn Extended Thinking aktiviert ist:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "messages": [...],
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10000
        },
        "context_management": {
            "edits": [
                {
                    "type": "clear_thinking_20251015",
                    "keep": {
                        "type": "thinking_turns",
                        "value": 2
                    }
                }
            ]
        }
    }'

Konfigurationsoptionen für Thinking-Block-Löschen

Die Strategie clear_thinking_20251015 unterstützt die folgende Konfiguration:

Beispielkonfigurationen:

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Strategien kombinieren

Sie können sowohl Thinking-Block-Löschen als auch Werkzeugergebnis-Löschen zusammen verwenden:

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    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 Werkzeugergebnis-Löschen

Kontextbearbeitungsantwort

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": [
            // 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
            }
        ]
    }
}

Für 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 Token-Zählungs-Endpunkt unterstützt Kontextverwaltung, sodass Sie eine Vorschau erhalten können, wie viele Token Ihr Prompt nach Anwendung der Kontextbearbeitung verwendet.

curl https://api.anthropic.com/v1/messages/count_tokens \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "messages": [
            {
                "role": "user",
                "content": "Continue our conversation..."
            }
        ],
        "tools": [...],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 5
                    }
                }
            ]
        }
    }'

{
    "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 dem Löschen (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ösch-Schwellenwert nähert, erhält Claude eine automatische Warnung, um wichtige Informationen zu bewahren. Dies ermöglicht Claude, Werkzeugergebnisse oder Kontext in seinen Memory-Dateien zu speichern, bevor sie aus der Gesprächshistorie gelöscht werden.

Diese Kombination ermöglicht es Ihnen:

• Wichtigen Kontext bewahren: Claude kann wesentliche Informationen aus Werkzeugergebnissen 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 Datei-Bearbeitungs-Workflow, in dem Claude viele Operationen durchführt, abgeschlossene Änderungen in Memory-Dateien zusammenfassen, während der Kontext wächst. Wenn Werkzeugergebnisse gelöscht werden, behält Claude über sein Memory-System Zugriff auf diese Informationen und kann effektiv weiterarbeiten.

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

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

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 serverseitigen Kontextbearbeitungsstrategien, die Inhalte löschen, weist die Komprimierung Claude an, die Gesprächshistorie zusammenzufassen, und ersetzt dann die vollständige Historie durch diese Zusammenfassung. Dies ermöglicht Claude, an langfristigen Aufgaben zu arbeiten, die sonst das Kontextfenster überschreiten würden.

Wie Komprimierung funktioniert

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

1. Schwellenwert-Überprü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 Benutzer-Turn eingefügt, und Claude generiert eine strukturierte Zusammenfassung, die in <summary></summary>-Tags eingewickelt ist.
3. Kontext-Ersetzung: Das SDK extrahiert die Zusammenfassung und ersetzt die gesamte Nachrichtenhistorie damit.
4. Fortsetzung: Das Gespräch wird von der Zusammenfassung aus fortgesetzt, wobei Claude dort weitermacht, wo es aufgehört hat.

Komprimierung verwenden

Fügen Sie compaction_control zu Ihrem tool_runner-Aufruf hinzu:

import anthropic

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=[...],
    messages=[
        {
            "role": "user",
            "content": "Analyze all the files in this directory and write a summary report."
        }
    ],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000
    }
)

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

final = runner.until_done()

Was während der Komprimierung passiert

Während das Gespräch wächst, sammelt sich die Nachrichtenhistorie 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. Die gesamte Historie 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 arbeitet von dieser Zusammenfassung aus weiter, als wäre sie die ursprüngliche Gesprächshistorie.

Konfigurationsoptionen

Wahl 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 einzuwickeln.

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

Standardmäßige Zusammenfassungsaufforderung

Die integrierte Zusammenfassungsaufforderung weist Claude an, eine strukturierte Fortsetzungszusammenfassung zu erstellen, die Folgendes umfasst:

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

Diese Struktur ermöglicht es Claude, die Arbeit effizient fortzusetzen, ohne wichtige Kontexte zu verlieren oder Fehler zu wiederholen.

Einschränkungen

Serverseitige Tools

Bei der Verwendung von serverseitigen 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-Suchoperation wie folgt aussehen:

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

Lösungsansätze:

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

Tool-Use-Grenzfälle

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

Überwachung der Komprimierung

Aktivieren Sie die Protokollierung, um zu verfolgen, wann die Komprimierung auftritt:

import logging

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

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

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 eine genaue Erinnerung an frühe Gesprächsdetails erfordern
• Workflows, die serverseitige Tools umfangreich nutzen
• Aufgaben, die einen genauen Status über viele Variablen hinweg beibehalten müssen