Komprimierung bei einem Token-Schwellenwert

„Threshold compaction“ (Schwellenwert-Komprimierung) ist die automatische Form der „compaction“ (Komprimierung): Du legst bei deinen gewöhnlichen Anfragen einen „token threshold“ (Token-Schwellenwert) fest, und die API fasst älteren Kontext mitten in einer Anfrage zusammen, sobald der Schwellenwert erreicht ist. Sie wird neben der Komprimierung auf Anfrage unterstützt, bei der du selbst entscheidest, wann die Zusammenfassung geschrieben wird (siehe Komprimierung auf Anfrage). Wie du zwischen beiden wählst, erfährst du unter Wähle, wie komprimiert werden soll.

Die Komprimierung erweitert die effektive Kontextlänge für lang laufende Unterhaltungen und Aufgaben, indem älterer Kontext automatisch zusammengefasst wird, wenn sich die Unterhaltung der Grenze des „context window“ (Kontextfenster) nähert. Außerdem hält sie den aktiven Kontext klein: Wenn eine Unterhaltung wächst, nimmt die Antwortqualität ab, daher ersetzt die Komprimierung älteren Inhalt durch eine prägnante Zusammenfassung.

Das ist ideal für:

• Chatbasierte Unterhaltungen mit mehreren Turns, bei denen Nutzer einen Chat über einen langen Zeitraum verwenden sollen
• Aufgabenorientierte Prompts, die viel Folgearbeit erfordern (oft „tool use“ (Tool-Nutzung)), die das Kontextfenster überschreiten könnte

Wie Komprimierung funktioniert

Wenn die Komprimierung aktiviert ist, fasst Claude deine Unterhaltung automatisch zusammen, sobald sie den konfigurierten Token-Schwellenwert erreicht. Die API:

1. Erkennt, wann die Eingabe-Token deinen angegebenen Trigger-Schwellenwert erreichen.
2. Erstellt eine Zusammenfassung der aktuellen Unterhaltung.
3. Erzeugt einen compaction-Block, der die Zusammenfassung enthält.
4. Setzt die Antwort mit dem komprimierten Kontext fort.

Hänge bei nachfolgenden Anfragen die Antwort an deine Nachrichten an. Die API verwirft automatisch alle Inhaltsblöcke vor dem compaction-Block und setzt die Unterhaltung ab der Zusammenfassung fort.

Grundlegende Verwendung

Aktiviere die Komprimierung, indem du die Strategie compact_20260112 zu context_management.edits in deiner Messages-API-Anfrage hinzufügst.

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Help me build a website"}]

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

# Hänge die Antwort (inklusive eines etwaigen Compaction-Blocks) an, um die Unterhaltung fortzusetzen
messages.append({"role": "assistant", "content": response.content})

Parameter

Trigger-Konfiguration

Lege mit dem Parameter trigger fest, wann die Komprimierung ausgelöst wird:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

Benutzerdefinierte Zusammenfassungsanweisungen

Der Standard-Zusammenfassungs-Prompt variiert je nach Modell. Jeder Standard-Prompt weist Claude an, eine Zusammenfassung innerhalb von <summary></summary>-Tags zu schreiben, die die Informationen enthält, die zum Fortsetzen der Aufgabe in einem zukünftigen Kontextfenster benötigt werden. Einige Modelle verwenden beispielsweise den folgenden Prompt:

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

Du kannst über den Parameter instructions benutzerdefinierte Anweisungen angeben. Benutzerdefinierte Anweisungen ergänzen den Standard-Prompt nicht. Sie ersetzen ihn vollständig:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

Bei Claude 5.1 und neueren Modellen fasst eine Anfrage mit benutzerdefinierten instructions nur die sichtbare Unterhaltung zusammen: Frühere Thinking-Blöcke sind nicht Teil der Eingabe für die Zusammenfassung.

Pausieren nach der Komprimierung

Verwende pause_after_compaction, um die API nach dem Erstellen der Komprimierungszusammenfassung zu pausieren. So kannst du zusätzliche Inhaltsblöcke hinzufügen (etwa um aktuelle Nachrichten oder bestimmte anweisungsorientierte Nachrichten zu erhalten), bevor die API mit der Antwort fortfährt.

Wenn diese Option aktiviert ist, gibt die API nach dem Erstellen des Komprimierungsblocks eine Nachricht mit dem Stop-Grund compaction zurück:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Prüfe, ob die Compaction eine Pause ausgelöst hat
if response.stop_reason == "compaction":
    # Antwort enthält nur den Compaction-Block
    messages.append({"role": "assistant", "content": response.content})

    # Setze die Anfrage fort
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

Die API pausiert auch dann, wenn keine Zusammenfassung erstellt wird. Der content des compaction-Blocks ist dann null, behalte also die ursprünglichen Nachrichten bei, wenn du fortfährst. Wenn Schutzmaßnahmen die Zusammenfassung blockieren, ist content ebenfalls null und der Stop-Grund ist refusal statt compaction. stop_details gibt die Richtlinienkategorie an, falls es eine gibt. Fahre in beiden Fällen auf die gleiche Weise fort: Suche nach dem compaction-Block, statt stop_reason zu prüfen, wie es das Beispiel, das aktuelle Nachrichten erhält, tut.

Ein Gesamt-Token-Budget durchsetzen

Wenn ein Modell an langen Aufgaben mit vielen Iterationen der Tool-Nutzung arbeitet, kann der gesamte Token-Verbrauch erheblich wachsen. Du kannst pause_after_compaction mit einem Komprimierungszähler kombinieren, um die kumulierte Nutzung abzuschätzen und die Aufgabe geordnet abzuschließen, sobald ein Budget erreicht ist.

Dieses Beispiel erscheint nur in den SDK-Sprachen: Sein Nutzen liegt in der Logik zur Budgetverfolgung rund um die Anfrage. Die reine Anfrage kombiniert den trigger aus Trigger-Konfiguration mit pause_after_compaction aus Pausieren nach der Komprimierung.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD},
                "pause_after_compaction": True,
            }
        ]
    },
)

if response.stop_reason == "compaction":
    n_compactions += 1
    messages.append({"role": "assistant", "content": response.content})

    # Schätze die insgesamt verbrauchten Tokens; fordere bei Budgetüberschreitung zum Abschluss auf
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

Arbeiten mit Komprimierungsblöcken

Wenn die Komprimierung ausgelöst wird, gibt die API am Anfang der Assistant-Antwort einen compaction-Block zurück.

Eine lang laufende Unterhaltung kann zu mehreren Komprimierungen führen. Der letzte Komprimierungsblock spiegelt den endgültigen Zustand des Prompts wider und ersetzt den Inhalt davor durch die erstellte Zusammenfassung.

{
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: The user requested help building a web scraper..."
    },
    {
      "type": "text",
      "text": "Based on our conversation so far..."
    }
  ]
}

Komprimierungsblöcke zurückgeben

Du musst den compaction-Block bei nachfolgenden Anfragen an die API zurückgeben, um die Unterhaltung mit dem verkürzten Prompt fortzusetzen. Am einfachsten ist es, den gesamten Antwortinhalt an deine Nachrichten anzuhängen:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# Nach Erhalt einer Antwort mit einem Compaction-Block
messages.append({"role": "assistant", "content": response.content})

# Setze die Unterhaltung fort
messages.append({"role": "user", "content": "Now add error handling"})

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

Verwende in Python client.beta.messages, wie es die Beispiele auf dieser Seite tun. Wenn du client.messages aufrufst und Blöcke selbst serialisierst, fügt ein einfaches model_dump() dem compaction-Block text: null und citations: null hinzu. Die API lehnt die Anfrage dann mit einem 400-Fehler ab (Extra inputs are not permitted). Verwende stattdessen to_dict() oder model_dump(exclude_none=True). Ab der Zusammenfassung fortfahren gibt denselben Hinweis für die Komprimierung auf Anfrage.

Wenn die API einen compaction-Block empfängt, werden alle Inhaltsblöcke davor ignoriert. Du kannst entweder:

• Die ursprünglichen Nachrichten in deiner Liste behalten und die API das Entfernen des komprimierten Inhalts übernehmen lassen
• Die komprimierten Nachrichten manuell verwerfen und nur den Komprimierungsblock und alles danach einschließen

Wenn keine Zusammenfassung erstellt wird, ist der content des Blocks null und die API ignoriert den Block. Es wird nichts komprimiert, behalte also die ursprünglichen Nachrichten bei.

Bei Claude 5.1 und neueren Modellen werden Thinking-Blöcke von vor einem compaction-Block nicht übernommen, sodass die Zusammenfassung alles ist, was das Modell von dieser früheren Arbeit hat. Wenn du eigene instructions schreibst, sag dem Modell, was die Zusammenfassung beibehalten muss; siehe Dem Modell sagen, was es in Compaction-Zusammenfassungen bewahren soll.

Streaming

Der Komprimierungsblock wird anders gestreamt als Textblöcke. Du erhältst ein content_block_start-Event, gefolgt von einem einzelnen content_block_delta mit dem vollständigen Inhalt der Zusammenfassung (kein zwischenzeitliches Streaming) und anschließend ein content_block_stop-Event.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]

with client.beta.messages.stream(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
    for event in stream:
        match event.type:
            case "content_block_start":
                block = event.content_block
                match block.type:
                    case "compaction":
                        print("Compaction started...")
                    case "text":
                        print("Text response started...")

            case "content_block_delta":
                delta = event.delta
                match delta.type:
                    case "compaction_delta":
                        print(f"Compaction complete: {len(delta.content or '')} chars")
                    case "text_delta":
                        print(delta.text, end="", flush=True)

    # Hole die endgültige akkumulierte Nachricht
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Prompt-Caching

Die Komprimierung funktioniert gut mit „prompt caching“ (Prompt-Caching). Du kannst einen cache_control-Breakpoint auf Komprimierungsblöcke setzen, um den zusammengefassten Inhalt zu cachen.

{
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "[summary text]",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Based on our conversation..."
    }
  ]
}

Cache-Treffer mit System-Prompts maximieren

Wenn eine Komprimierung stattfindet, wird die Zusammenfassung zu neuem Inhalt, der in den Cache geschrieben werden muss. Ohne zusätzliche Cache-Breakpoints würde dies auch jeden gecachten „system prompt“ (System-Prompt) ungültig machen, sodass er zusammen mit der Komprimierungszusammenfassung erneut gecacht werden müsste.

Um die Cache-Trefferquote zu maximieren, füge am Ende deines System-Prompts einen cache_control-Breakpoint hinzu. Dadurch bleibt der System-Prompt getrennt von der Unterhaltung gecacht, sodass bei einer Komprimierung:

• Der Cache des System-Prompts gültig bleibt und aus dem Cache gelesen wird
• Nur die Komprimierungszusammenfassung als neuer Cache-Eintrag geschrieben werden muss

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    system=[
        {
            "type": "text",
            "text": "You are a helpful coding assistant...",
            "cache_control": {
                "type": "ephemeral"
            },  # Cache the system prompt separately
        }
    ],
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

So bleiben lange System-Prompts über mehrere Komprimierungsereignisse hinweg während einer Unterhaltung gecacht.

Nutzung verstehen

Die Komprimierung erfordert einen zusätzlichen Sampling-Schritt, der zu den „rate limits“ (Ratenlimits) und zur Abrechnung beiträgt. Die API gibt in der Antwort detaillierte Nutzungsinformationen zurück:

{
  "usage": {
    "input_tokens": 23000,
    "output_tokens": 1000,
    "iterations": [
      {
        "type": "compaction",
        "input_tokens": 180000,
        "output_tokens": 3500
      },
      {
        "type": "message",
        "input_tokens": 23000,
        "output_tokens": 1000
      }
    ]
  }
}

Das Array iterations zeigt die Nutzung für jede Sampling-Iteration. Wenn eine Komprimierung stattfindet, siehst du eine compaction-Iteration, gefolgt von der Haupt-Iteration message. Die Top-Level-Werte input_tokens und output_tokens stimmen in diesem Beispiel genau mit der message-Iteration überein, da es nur eine Iteration ohne Komprimierung gibt. Die Token-Zahlen der letzten Iteration spiegeln die effektive Kontextgröße nach der Komprimierung wider.

Kombination mit anderen Funktionen

Server-Tools

Bei der Verwendung von Server-Tools (wie der Websuche) wird der Komprimierungs-Trigger zu Beginn jeder Sampling-Iteration geprüft. Je nach deinem Trigger-Schwellenwert und der Menge der erzeugten Ausgabe kann die Komprimierung innerhalb einer einzelnen Anfrage mehrmals stattfinden.

Token-Zählung

Der Endpunkt zur Token-Zählung (/v1/messages/count_tokens) wendet vorhandene compaction-Blöcke in deinem Prompt an, löst aber keine neuen Komprimierungen aus. Verwende ihn, um deine effektive Token-Anzahl nach vorherigen Komprimierungen zu prüfen:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

print(f"Current tokens: {count_response.input_tokens}")
print(f"Original tokens: {count_response.context_management.original_input_tokens}")

Beispiele

Hier ist ein vollständiges Beispiel einer lang laufenden Unterhaltung mit Komprimierung:

client = anthropic.Anthropic()

messages: list[dict] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Hänge die Antwort an (Compaction-Blöcke werden automatisch einbezogen)
    messages.append({"role": "assistant", "content": response.content})

    # Gib den Textinhalt zurück
    return next((block.text for block in response.content if block.type == "text"), "")


# Führe eine lange Unterhaltung
print(chat("Briefly, help me build a Python web scraper"))
print(chat("Briefly, add support for JavaScript-rendered pages"))
print(chat("Briefly, add rate limiting and error handling"))
# Rufe chat() so lange auf, wie die Unterhaltung es erfordert

Bei Claude 5.1 und neueren Modellen bestehen Thinking-Blöcke in jedem Assistenten-Turn, den du nach dem Compaction-Block erneut einfügst, die Präfixprüfung nicht, da sie erzeugt wurden, als der vollständige Verlauf vorhanden war. Entferne die thinking- und redacted_thinking-Blöcke aus diesen Turns. Alternativ kannst du thinking.block_binding.prefix_mismatch_behavior: "drop_block" zusammen mit dem thinking-binding-controls-2026-08-01 Beta-Header senden. Die beibehaltenen Text- und Tool-Blöcke können unverändert bleiben. Wenn du die API alles zusammenfassen lässt, ohne frühere Turns erneut einzufügen, vermeidest du dieses Problem. Bei Claude Sonnet 5.5 und Claude Haiku 5.5 funktioniert block_binding nur mit thinking: {"type": "adaptive"}. Bei jeder anderen Nachdenken-Einstellung auf diesen Modellen musst du die Blöcke entfernen.

Hier ist ein Beispiel, das pause_after_compaction verwendet, um den vorherigen Austausch und die aktuelle Nutzernachricht (insgesamt drei Nachrichten) zu erhalten, statt sie zusammenzufassen. Es lässt deren Text- und Tool-Blöcke unverändert, entfernt die thinking- und redacted_thinking-Blöcke aus dem erhaltenen Assistant-Turn und verwirft diesen Turn, wenn sonst nichts übrig bleibt:

from typing import Any

client = anthropic.Anthropic()

messages: list[dict[str, Any]] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Suche nach dem Komprimierungsblock, nicht nach dem Stop-Grund:
    # stop_reason ist "refusal", nicht "compaction", wenn die Zusammenfassung blockiert wurde
    compaction_block = next(
        (block for block in response.content if block.type == "compaction"), None
    )

    # Ersetze den Verlauf nur, wenn eine Zusammenfassung erstellt wurde
    if compaction_block is not None and compaction_block.content is not None:
        # Behalte den vorherigen Austausch + aktuelle Nutzernachricht bei (3 Nachrichten)
        # indem du sie nach dem Komprimierungsblock einfügst, ohne Thinking-
        # Blöcke; ein Assistant-Turn ohne Inhalt wird verworfen
        preserved_messages = [
            {
                **message,
                "content": [
                    block
                    for block in message["content"]
                    if block.type not in ("thinking", "redacted_thinking")
                ],
            }
            if message["role"] == "assistant"
            else message
            for message in messages[-3:]
        ]
        preserved_messages = [m for m in preserved_messages if m["content"]]

        # Erstelle neue Nachrichtenliste: Komprimierung + beibehaltene Nachrichten
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Aktualisiere die Nachrichtenliste entsprechend der Komprimierung
        messages.clear()
        messages.extend(messages_after_compaction)

    if compaction_block is not None:
        # Setze die Anfrage fort, mit vollem Verlauf, falls keine Zusammenfassung existiert
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-5-5",
            max_tokens=4096,
            messages=messages,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

    # Hänge die finale Antwort an
    messages.append({"role": "assistant", "content": response.content})

    # Gib den Textinhalt zurück
    return next((block.text for block in response.content if block.type == "text"), "")


# Führe eine lange Konversation
print(chat("Briefly, help me build a Python web scraper"))
print(chat("Briefly, add support for JavaScript-rendered pages"))
print(chat("Briefly, add rate limiting and error handling"))
# Rufe chat() so lange auf, wie die Konversation es erfordert

Aktuelle Einschränkungen

• Dasselbe Modell für die Zusammenfassung: Das in deiner Anfrage angegebene Modell wird für die Zusammenfassung verwendet. Es gibt keine Option, ein anderes (zum Beispiel günstigeres) Modell für die Zusammenfassung zu verwenden.

• Die Komprimierung kann fehlschlagen, wenn Tools definiert sind: Wenn deine Anfrage tools enthält, ruft das Modell während des internen Zusammenfassungsschritts gelegentlich ein Tool auf, anstatt eine Zusammenfassung zu schreiben. In diesem Fall enthält die Antwort einen compaction-Block mit content: null. Um dies zu verhindern, setze instructions auf einen Prompt, der dem Modell ausdrücklich sagt, keine Tools aufzurufen, zum Beispiel:

  Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only.

  

Nächste Schritte

Verfügbarkeit

Schwellenwert-Komprimierung ist auf ausgewählten Modellen in der Beta und für Zero Data Retention berechtigt.

API-Unterstützung

Mit Beta-Headern kannst du auf experimentelle Funktionen und neue Modellfähigkeiten zugreifen, bevor sie Teil der Standard-API werden.