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"}]},
    )

Ein Gesamt-Token-Budget durchsetzen

Wenn ein Modell an langen Aufgaben mit vielen Iterationen der Tool-Nutzung arbeitet, kann der gesamte Token-Verbrauch erheblich ansteigen. 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})

    # Verbrauchte Tokens schätzen; bei Budgetüberschreitung zum Abschluss auffordern
    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 entfernen und nur den Komprimierungsblock und alles danach einschließen

Bei Claude Fable 5.1, Claude Mythos 5.1 und Claude Opus 5.5 werden Thinking-Blöcke von vor einem compaction-Block nicht übernommen, sodass die Zusammenfassung alles ist, was dem Modell von dieser früheren Arbeit bleibt. Wenn du eigene instructions schreibst, teile dem Modell mit, was die Zusammenfassung enthalten 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 final 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},
                }
            ]
        },
    )

    # Antwort anhängen (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("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# Rufe chat() so lange auf, wie die Unterhaltung es erfordert

Entferne bei Claude Fable 5.1 und Claude Opus 5.5 die thinking- und redacted_thinking-Blöcke aus jedem Assistant-Turn, den du nach dem Komprimierungsblock erneut einfügst, oder sende thinking.block_binding.prefix_mismatch_behavior: "drop_block" mit dem Beta-Header thinking-binding-controls-2026-08-01. Diese Blöcke wurden erzeugt, als der vollständige Verlauf vorhanden war, daher bestehen sie die Unterhaltungsprüfung nicht mehr. Wo die Prüfung durchgesetzt wird, wird die Fortsetzungsanfrage mit einem 400-Fehler abgelehnt. Die erhaltenen 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.

Hier ist ein Beispiel, das pause_after_compaction verwendet, um den vorherigen Austausch und die aktuelle Nutzernachricht (insgesamt drei Nachrichten) wörtlich zu erhalten, anstatt sie zusammenzufassen:

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,
                }
            ]
        },
    )

    # Prüfe, ob eine Compaction stattgefunden und pausiert hat
    if response.stop_reason == "compaction":
        # Hole den Compaction-Block aus der Antwort
        compaction_block = response.content[0]

        # Behalte den vorherigen Austausch + aktuelle Nutzernachricht bei (3 Nachrichten)
        # indem du sie nach dem Compaction-Block einfügst
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

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

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

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

    # 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("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now 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

Compatibility