Komprimierung

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Serverseitige Komprimierung ist die empfohlene Strategie zur Verwaltung von Kontext in langfristigen Konversationen und agentengesteuerten Workflows. Sie verwaltet den Kontext automatisch mit minimalem Integrationaufwand.

Komprimierung erweitert die effektive Kontextlänge für langfristige Konversationen und Aufgaben, indem älteren Kontext automatisch zusammengefasst wird, wenn sich das Kontextfenster-Limit nähert. Es geht nicht nur darum, unter einem Token-Limit zu bleiben. Mit längeren Konversationen haben Modelle Schwierigkeiten, den Fokus über die gesamte Historie zu bewahren. Komprimierung hält den aktiven Kontext fokussiert und leistungsfähig, indem veraltete Inhalte durch prägnante Zusammenfassungen ersetzt werden.

Für einen tieferen Einblick, warum lange Kontexte degradieren und wie Komprimierung hilft, siehe Effective context engineering.

Dies ist ideal für:

Chat-basierte, mehrteilige Konversationen, bei denen Sie möchten, dass Benutzer einen Chat über einen längeren Zeitraum verwenden
Aufgabenorientierte Prompts, die viel Folgework erfordern (oft Tool-Nutzung), die das Kontextfenster überschreiten können

Komprimierung ist in Beta. Fügen Sie den Beta-Header compact-2026-01-12 in Ihre API-Anfragen ein, um diese Funktion zu nutzen.

Unterstützte Modelle

Komprimierung wird auf den folgenden Modellen unterstützt:

Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-4-6)

Wie Komprimierung funktioniert

Wenn Komprimierung aktiviert ist, fasst Claude Ihre Konversation automatisch zusammen, wenn sie sich dem konfigurierten Token-Schwellenwert nähert. Die API:

Erkennt, wenn Eingabe-Token Ihren angegebenen Auslöseschwellenwert überschreiten.
Generiert eine Zusammenfassung der aktuellen Konversation.
Erstellt einen compaction-Block mit der Zusammenfassung.
Setzt die Antwort mit dem komprimierten Kontext fort.

Bei nachfolgenden Anfragen fügen Sie die Antwort zu Ihren Nachrichten hinzu. Die API löscht automatisch alle Nachrichtenblöcke vor dem compaction-Block und setzt die Konversation von der Zusammenfassung aus fort.

Flussdiagramm, das den Komprimierungsprozess zeigt: Wenn Eingabe-Token den Auslöseschwellenwert überschreiten, generiert Claude eine Zusammenfassung in einem Komprimierungsblock und setzt die Antwort mit dem komprimierten Kontext fort

Grundlegende Verwendung

Aktivieren Sie Komprimierung, indem Sie die compact_20260112-Strategie zu context_management.edits in Ihrer Messages API-Anfrage hinzufügen.

Parameter

Parameter	Typ	Standard	Beschreibung
`type`	string	Erforderlich	Muss `"compact_20260112"` sein
`trigger`	object	150.000 Token	Wann Komprimierung ausgelöst wird. Muss mindestens 50.000 Token sein.
`pause_after_compaction`	boolean	`false`	Ob nach der Generierung der Komprimierungszusammenfassung pausiert werden soll
`instructions`	string	`null`	Benutzerdefinierter Zusammenfassungs-Prompt. Ersetzt den Standard-Prompt vollständig, wenn bereitgestellt.

Trigger-Konfiguration

Konfigurieren Sie, wann Komprimierung ausgelöst wird, mit dem trigger-Parameter:

Benutzerdefinierte Zusammenfassungsanweisungen

Standardmäßig verwendet Komprimierung den folgenden Zusammenfassungs-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.

Sie können benutzerdefinierte Anweisungen über den instructions-Parameter bereitstellen, um diesen Prompt vollständig zu ersetzen. Benutzerdefinierte Anweisungen ergänzen nicht den Standard; sie ersetzen ihn vollständig:

Pause nach Komprimierung

Verwenden Sie pause_after_compaction, um die API nach der Generierung der Komprimierungszusammenfassung zu pausieren. Dies ermöglicht es Ihnen, zusätzliche Inhaltsblöcke hinzuzufügen (z. B. um aktuelle Nachrichten oder spezifische anweisungsorientierte Nachrichten zu bewahren), bevor die API mit der Antwort fortfährt.

Wenn aktiviert, gibt die API eine Nachricht mit dem compaction Stop-Grund nach der Generierung des Komprimierungsblocks zurück:

Durchsetzung eines Gesamttoken-Budgets

Wenn ein Modell an langen Aufgaben mit vielen Tool-Use-Iterationen arbeitet, kann der Gesamttoken-Verbrauch erheblich wachsen. Sie können pause_after_compaction mit einem Komprimierungszähler kombinieren, um die kumulative Nutzung zu schätzen und die Aufgabe elegant abzuschließen, sobald ein Budget erreicht ist:

Python

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

    # Estimate total tokens consumed; prompt wrap-up if over budget
    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 einen compaction Block am Anfang der Assistenten-Antwort zurück.

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

Output

{
  "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

Sie müssen den compaction Block bei nachfolgenden Anfragen an die API zurückgeben, um die Konversation mit dem verkürzten Prompt fortzusetzen. Der einfachste Ansatz besteht darin, den gesamten Antwortinhalt an Ihre Nachrichten anzuhängen:

Wenn die API einen compaction Block empfängt, werden alle Inhaltsblöcke davor ignoriert. Sie können entweder:

Die ursprünglichen Nachrichten in Ihrer Liste behalten und die API den komprimierten Inhalt entfernen lassen
Die komprimierten Nachrichten manuell löschen und nur den Komprimierungsblock und danach einbeziehen

Streaming

Beim Streaming von Antworten mit aktivierter Komprimierung erhalten Sie ein content_block_start Ereignis, wenn die Komprimierung beginnt. Der Komprimierungsblock wird anders als Textblöcke gestreamt. Sie erhalten ein content_block_start Ereignis, gefolgt von einem einzelnen content_block_delta mit dem vollständigen Zusammenfassungsinhalt (kein zwischenzeitliches Streaming) und dann ein content_block_stop Ereignis.

Prompt-Caching

Komprimierung funktioniert gut mit Prompt-Caching. Sie können einen cache_control-Breakpoint auf Komprimierungsblöcken hinzufügen, um den zusammengefassten Inhalt zu cachen. Der ursprüngliche komprimierte Inhalt wird ignoriert.

{
  "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 auftritt, 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 ungültig machen und erfordern, dass dieser zusammen mit der Komprimierungszusammenfassung neu gecacht wird.

Um die Cache-Trefferquoten zu maximieren, fügen Sie einen cache_control-Breakpoint am Ende Ihres System-Prompts hinzu. Dies hält den System-Prompt separat vom Gespräch gecacht, sodass bei einer Komprimierung:

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

Dieser Ansatz ist besonders vorteilhaft für lange System-Prompts, da diese auch über mehrere Komprimierungsereignisse hinweg in einem Gespräch gecacht bleiben.

Nutzung verstehen

Die Komprimierung erfordert einen zusätzlichen Sampling-Schritt, der zu Rate Limits und Abrechnung beiträgt. Die API gibt detaillierte Nutzungsinformationen in der Antwort zurück:

Output

{
  "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 iterations-Array zeigt die Nutzung für jede Sampling-Iteration. Wenn eine Komprimierung auftritt, sehen Sie eine compaction-Iteration gefolgt von der Haupt-message-Iteration. Die input_tokens und output_tokens auf oberster Ebene entsprechen in diesem Beispiel genau der message-Iteration, da es nur eine Nicht-Komprimierungs-Iteration gibt. Die Token-Zählungen der letzten Iteration spiegeln die effektive Kontextgröße nach der Komprimierung wider.

Die input_tokens und output_tokens auf oberster Ebene enthalten nicht die Nutzung der Komprimierungs-Iteration. Sie spiegeln die Summe aller Nicht-Komprimierungs-Iterationen wider. Um die Gesamtzahl der verbrauchten und abgerechneten Token für eine Anfrage zu berechnen, summieren Sie alle Einträge im usage.iterations-Array.

Wenn Sie sich zuvor auf usage.input_tokens und usage.output_tokens für die Kostenverfolgung oder Auditing verlassen haben, müssen Sie Ihre Verfolgungslogik aktualisieren, um über usage.iterations zu aggregieren, wenn die Komprimierung aktiviert ist. Das iterations-Array wird nur gefüllt, wenn während der Anfrage eine neue Komprimierung ausgelöst wird. Das erneute Anwenden eines vorherigen compaction-Blocks verursacht keine zusätzlichen Komprimierungskosten, und die Nutzungsfelder auf oberster Ebene bleiben in diesem Fall genau.

Kombinieren mit anderen Funktionen

Server-Tools

Bei Verwendung von Server-Tools (wie Websuche) wird der Komprimierungs-Trigger am Anfang jeder Sampling-Iteration überprüft. Die Komprimierung kann mehrmals innerhalb einer einzelnen Anfrage auftreten, je nach Ihrem Trigger-Schwellenwert und der Menge der generierten Ausgabe.

Token-Zählung

Der Token-Zählungs-Endpunkt (/v1/messages/count_tokens) wendet vorhandene compaction-Blöcke in Ihrem Prompt an, löst aber keine neuen Komprimierungen aus. Verwenden Sie ihn, um Ihre effektive Token-Zählung nach vorherigen Komprimierungen zu überprüfen:

Beispiele

Hier ist ein vollständiges Beispiel einer langfristigen Konversation mit Komprimierung:

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

Aktuelle Einschränkungen

Gleiches Modell für Zusammenfassung: Das in Ihrer Anfrage angegebene Modell wird für die Zusammenfassung verwendet. Es gibt keine Option, ein anderes (z. B. günstigeres) Modell für die Zusammenfassung zu verwenden.

Nächste Schritte

Session Memory Compaction Cookbook

Erkunden Sie eine praktische Implementierung, die langfristige Konversationen mit sofortiger Session Memory Compaction mithilfe von Hintergrund-Threading und Prompt Caching verwaltet.

Kontextfenster

Erfahren Sie mehr über Kontextfenstergröße und Verwaltungsstrategien.

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-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

# Append the response (including any compaction block) to continue the conversation
messages.append({"role": "assistant", "content": response.content})

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

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

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

# Check if compaction triggered a pause
if response.stop_reason == "compaction":
    # Response contains only the compaction block
    messages.append({"role": "assistant", "content": response.content})

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

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})

# Continue the conversation
messages.append({"role": "user", "content": "Now add error handling"})

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

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

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

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

    # Get the final accumulated message
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    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"}]},
)

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    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}")

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-4-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Append response (compaction blocks are automatically included)
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
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"))
# ... continue as long as needed

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-4-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Check if compaction occurred and paused
    if response.stop_reason == "compaction":
        # Get the compaction block from the response
        compaction_block = response.content[0]

        # Preserve the prior exchange + current user message (3 messages)
        # by including them after the compaction block
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Build new message list: compaction + preserved messages
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Continue the request with the compacted context + preserved messages
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-7",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Update our message list to reflect the compaction
        messages.clear()
        messages.extend(messages_after_compaction)

    # Append the final response
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
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"))
# ... continue as long as needed