Komprimierung auf Anfrage

Mit „on-demand compaction“ (Komprimierung auf Anfrage) entscheidet deine Anwendung, wann eine Unterhaltung zusammengefasst wird: Du sendest eine Anfrage mit dem Parameter compaction, und Claude gibt anstelle einer Antwort eine Zusammenfassung zurück.

So funktioniert die Komprimierung auf Anfrage

Eine Komprimierungsanfrage ist von den Turns deiner Unterhaltung getrennt. Du sendest die Unterhaltung in ihrem aktuellen Stand mit dem Parameter compaction, und die Antwort enthält einen einzelnen compaction-Block. Der Block enthält die Zusammenfassung als lesbaren Text sowie eine Signatur. Sende ihn in zukünftigen Anfragen genau so, wie er zurückgekommen ist.

Von da an tritt der Block an die Stelle der Nachrichten, die er zusammenfasst. Er steht an erster Stelle in messages, die zusammengefassten Nachrichten werden entfernt, und dein nächster Turn folgt auf ihn. Claude sieht die Zusammenfassung dort, wo diese Nachrichten standen.

Eine Zusammenfassung anfordern

Sende den Beta-Header compact-2026-09-04 bei der Anfrage, die die Zusammenfassung anfordert, und bei jeder späteren Anfrage, die den signierten Block enthält. Um zu prüfen, ob ein Modell die Komprimierung auf Anfrage unterstützt, rufe die Models API mit dem Beta-Header auf und lies capabilities.compaction für jedes Modell aus. Du kannst compaction nicht mit context_management in einer Anfrage kombinieren.

Sende die Unterhaltung in ihrem aktuellen Stand mit "compaction": {"type": "summarize"}. Die API fasst jede Nachricht in der Anfrage einmal zusammen, generiert danach keine Antwort und gibt nur den Block mit stop_reason "compaction" zurück. Sende denselben system-Prompt und dieselben tools, die du für den Rest der Unterhaltung verwendest. Der Zusammenfasser liest sie, und wenn du Turns nach dem Block auf einem Modell mit „preserved thinking“ (beibehaltenem Denken) behältst, bleibt das Denken in diesen Turns nur gültig, wenn system und tools übereinstimmen. Die Unterhaltung in diesem Beispiel hat weder einen system-Prompt noch Tools, daher sendet die Anfrage keines von beiden:

from anthropic.types.beta import BetaMessageParam

client = anthropic.Anthropic()

history: list[BetaMessageParam] = [
    {
        "role": "user",
        "content": "I am building a recipe app. Help me name the main entities in the data model.",
    },
    {
        "role": "assistant",
        "content": "Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe.",
    },
    {"role": "user", "content": "Good. Now suggest field names for Recipe."},
]

response = client.beta.messages.create(
    model="claude-opus-5-5",
    # max_tokens begrenzt den gesamten Aufruf inkl. Denken, also plane mehrere tausend Token ein.
    max_tokens=4096,
    betas=["compact-2026-09-04"],
    messages=history,
    compaction={"type": "summarize"},
)
print(f"Stop reason: {response.stop_reason}")

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: the user is designing the data model for a recipe app. The entities agreed so far are Recipe, Ingredient, Step, and RecipeIngredient, which holds the quantity and unit. The user then asked for field names for Recipe.",
      "signature": "EuYBCkQY..."
    }
  ],
  "stop_reason": "compaction",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "iterations": [{ "type": "compaction", "input_tokens": 144, "output_tokens": 276 }]
  }
}

Der Zusammenfassungsaufruf verwendet das Modell, system, tools, die Thinking-Einstellungen und max_tokens der Anfrage. Der Zusammenfasser liest die Tool-Definitionen, führt aber nie ein Tool aus, und die Antwort enthält kein Thinking. max_tokens begrenzt den gesamten Aufruf, einschließlich des Denkens, das das Modell vor dem Schreiben der Zusammenfassung ausführt, also plane mehrere tausend Token ein. Komprimierungsnutzung zählen zeigt, wie der Aufruf abgerechnet wird.

Wenn der letzte assistant-Turn mit einem Tool-Aufruf endet, für den noch kein Ergebnis vorliegt, lehnt die API die Anfrage ab. Sende zuerst die Tool-Ergebnisse dieses Turns. Lass außerdem stop_sequences, das Structured-Output-Feld output_config.format und eine tool_choice vom Typ any oder tool weg. Sie hätten bei einem Zusammenfassungsaufruf keine Wirkung, und die API lehnt sie ab. Die Unterhaltung muss weiterhin in das „context window“ (Kontextfenster) des Modells passen, also komprimiere, bevor du es überschreitest, nicht danach.

Wenn du die Antwort per Streaming empfängst, kommt der Block vollständig an. Du erhältst ein content_block_start-Event mit dem vollständigen Block, dann content_block_stop, ohne content_block_delta-Events. ping-Events können davor oder dazwischen eintreffen.

Ab der Zusammenfassung fortfahren

Ersetze in deinem Verlauf die gesendeten Nachrichten durch die zurückgegebene Assistant-Nachricht. Behalte den compaction-Block genau so bei, wie die API ihn zurückgegeben hat, einschließlich seiner signature. Alle Turns, die nach dem Senden der Komprimierungsanfrage stattgefunden haben, folgen unverändert auf den Block – darauf baut Komprimierung im Hintergrund auf. Sende den Block bei jeder späteren Anfrage an erster Stelle, zusammen mit dem Beta-Header:

{
  "model": "claude-opus-5-5",
  "max_tokens": 2048,
  "messages": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "compaction",
          "content": "Summary of the conversation: the user is designing the data model for a recipe app. The entities agreed so far are Recipe, Ingredient, Step, and RecipeIngredient, which holds the quantity and unit. The user then asked for field names for Recipe.",
          "signature": "EuYBCkQY..."
        }
      ]
    },
    {
      "role": "assistant",
      "content": "For Recipe, use title, description, servings, prep_minutes, and cook_minutes. Add created_at and updated_at timestamps."
    },
    { "role": "user", "content": "Now do the same for Ingredient." }
  ]
}

Dieses Beispiel setzt das Anfragebeispiel fort, das mit einem user-Turn endete; das Diagramm zeigt den einfacheren Fall, in dem während des Schreibens der Zusammenfassung kein Turn stattfindet. Hier ist die zweite assistant-Nachricht die Antwort auf den letzten zusammengefassten user-Turn. Sie kam an, während die Zusammenfassung geschrieben wurde, und gehörte daher nicht zu den zusammengefassten Nachrichten. Zwei aufeinanderfolgende assistant-Nachrichten sind hier in Ordnung, weil der Block weiterhin an erster Stelle steht.

Die API setzt die Zusammenfassung dort ein, wo der Block steht, und gibt jede spätere Nachricht unverändert an Claude weiter. Befolge diese Regeln:

• Setze den Block an die erste Stelle in messages, entweder als eigene assistant-Nachricht oder als ersten Content-Block der ersten Nachricht, unabhängig davon, ob es sich um eine user- oder assistant-Nachricht handelt.
• Entferne die zusammengefassten Nachrichten. Wenn noch welche vor dem Block stehen, gibt die Anfrage einen 400-Fehler zurück (compaction_block_misplaced).
• Sende genau einen compaction-Block pro Anfrage, und zwar bei jeder späteren Anfrage.

Die Schwellenwert-Komprimierung funktioniert umgekehrt: Ihr Block folgt auf die Nachrichten, die er zusammenfasst, und die API entfernt diese für dich. Siehe Komprimierungsblöcke zurückgeben.

Verwende in Python client.beta.messages, wie es die Beispiele auf dieser Seite tun. Wenn du client.messages aufrufst und Blöcke selbst serialisierst, verwende to_dict() oder model_dump(exclude_none=True): Ein einfaches model_dump() fügt dem Block citations: null und text: null hinzu, und die API lehnt ihn ab.

Wenn du Turns nach dem Block behältst und deren Thinking-Blöcke zurücksendest, findest du die Bedingungen, unter denen dieses Denken gültig bleibt, unter Komprimierung und beibehaltenes Denken.

Erneut komprimieren

Um eine Unterhaltung zu komprimieren, die bereits mit einem Block beginnt, sende erneut compaction. Der neue Block fasst die alte Zusammenfassung und alles danach zusammen. Sende von da an nur noch den neuesten Block.

In einer Schleife komprimieren

Nach jedem Turn addiert die Schleife die Eingabe- und Ausgabe-Token der letzten Antwort, weil die nächste Anfrage auch die Antwort mitsendet. Wenn diese Summe ein Limit überschreitet und noch ein weiterer Turn folgt, sendet sie eine Komprimierungsanfrage mit demselben Modell und demselben system-Prompt, prüft stop_reason, ersetzt ihren Verlauf durch die zurückgegebene Nachricht und gibt aus, vor welchem Turn sie komprimiert hat. Das Limit von 2.500 Token im Beispiel ist absichtlich niedrig, damit auch eine kurze Unterhaltung komprimiert wird. Setze deines nahe an dein tatsächliches Eingabebudget.

from anthropic.types.beta import BetaMessageParam

client = anthropic.Anthropic()

# Setze dies nahe an dein tatsächliches Input-Budget. Hier ist es niedrig, damit schon ein kurzes Gespräch kompaktiert wird.
COMPACT_AT_TOKENS = 2500
SYSTEM = "You help design a recipe app's data model. Keep answers short."

QUESTIONS = [
    "What are the main entities in the data model?",
    "Which fields should Recipe have?",
    "Which fields should Ingredient have?",
    "Which fields should RecipeIngredient have?",
    "Which fields should Step have?",
    "Which indexes should these tables have?",
    "Which fields should be required?",
    "Which fields should have default values?",
]

history: list[BetaMessageParam] = []
for turn, question in enumerate(QUESTIONS, start=1):
    history.append({"role": "user", "content": question})
    response = client.beta.messages.create(
        model="claude-opus-5-5",
        max_tokens=8192,
        system=SYSTEM,
        betas=["compact-2026-09-04"],
        messages=history,
    )
    history.append({"role": "assistant", "content": response.content})

    # Die nächste Anfrage sendet diese Antwort mit, also zähle sie mit.
    conversation_tokens = response.usage.input_tokens + response.usage.output_tokens
    if conversation_tokens > COMPACT_AT_TOKENS and turn < len(QUESTIONS):
        summary = client.beta.messages.create(
            model="claude-opus-5-5",
            max_tokens=4096,
            system=SYSTEM,
            betas=["compact-2026-09-04"],
            messages=history,
            compaction={"type": "summarize"},
        )
        if summary.stop_reason == "compaction":
            history = [{"role": "assistant", "content": summary.content}]
            print(f"Compacted before turn {turn + 1}")

Die Prüfung von stop_reason erfolgt, bevor der Code nach dem Block sucht; Fehlende Zusammenfassung oder Fehler behandeln erklärt, warum. Der Verlauf wird ersetzt, nicht ergänzt: Die zurückgegebene Nachricht ersetzt jede Nachricht, die die Anfrage enthielt, gemäß den Regeln unter Ab der Zusammenfassung fortfahren. Wenn keine Zusammenfassung zurückkommt, behält die Schleife ihren Verlauf und fragt nach dem nächsten Turn erneut an.

Der Tool-Runner des SDK in Python, TypeScript, C#, Go und Java kann die Komprimierungsanfrage für dich senden. Wenn du dich für eine Komprimierung entscheidest, rufe compact_before_next_turn() auf dem Runner auf (compactBeforeNextTurn() in TypeScript und Java, CompactBeforeNextTurn() in C# und Go). Sobald der aktuelle Turn und seine Tool-Aufrufe abgeschlossen sind, sendet der Runner die Komprimierungsanfrage und ersetzt seinen Verlauf durch die zurückgegebene Nachricht. Erstelle den Runner mit der Beta compact-2026-09-04, da der Runner sie nicht hinzufügt. Der Runner erstellt die Anfrage aus seinen eigenen Parametern und lässt context_management weg. Wenn diese Parameter stop_sequences, eine tool_choice vom Typ any oder tool oder ein Structured-Output-Feld output_config.format enthalten, lehnt die API die Anfrage mit einem 400-Fehler ab. Eine Zusammenfassung anfordern erklärt, warum. Der Runner verweigert die Komprimierung, solange sein context_management eine Komprimierungsbearbeitung enthält, verwende also nur eine Art von Komprimierung pro Runner.

Wann komprimiert werden sollte

Du kannst nach jedem abgeschlossenen Turn eine Komprimierungsanfrage senden, also entscheidet dein Code, wann.

Um abzuschätzen, wie groß die nächste Anfrage sein wird, addiere input_tokens und output_tokens aus der usage der letzten Antwort, wie es die Schleife tut. Mit Prompt-Caching zählt input_tokens nur die Token nach dem letzten Cache-Breakpoint, addiere also zusätzlich cache_read_input_tokens und cache_creation_input_tokens. Du kannst dieselben Nachrichten auch an den Endpunkt für Token-Zählung senden.

Vergleiche diese Zahl mit einem von dir gewählten Limit unterhalb des Kontextfensters des Modells.

Eigenen Zusammenfassungs-Prompt schreiben

Ohne instructions verwendet die API ihren eigenen Zusammenfassungs-Prompt. Ein nicht leerer instructions-String (bis zu 16.384 Zeichen) ersetzt diesen Prompt vollständig. Zum Beispiel:

{
  "compaction": {
    "type": "summarize",
    "instructions": "Summarize this recipe app design conversation. Preserve every entity and field name agreed so far, and the user's latest open request. Do not call tools; respond with the summary text only."
  }
}

Der Zusammenfasser liest die gesamte Unterhaltung, einschließlich früheren Denkens, mit oder ohne instructions. Gib in deinen instructions an, was die Zusammenfassung beibehalten muss, und weise das Modell an, keine Tools aufzurufen. Der Zusammenfassungsaufruf unterliegt denselben Schutzmaßnahmen wie jede andere Anfrage.

Fehlende Zusammenfassung oder Fehler behandeln

Eine Zusammenfassung wird nur erzeugt, wenn der Zusammenfassungsaufruf normal mit Text und ohne Tool-Aufruf endet. Andernfalls ist die Antwort trotzdem ein 200 mit leerem content, prüfe also stop_reason, bevor du nach dem Block suchst. Der Aufruf wird trotzdem abgerechnet und in usage.iterations ausgewiesen, mit einer Nutzung von null, wenn kein Aufruf erfolgen konnte. Der stop_reason ist derjenige, mit dem der Zusammenfassungsaufruf geendet hat. In jedem Fall kannst du ohne Zusammenfassung fortfahren und später komprimieren.

Der Zusammenfassungsaufruf unterliegt denselben Schutzmaßnahmen wie deine anderen Anfragen. Nach einem "refusal" gibt stop_details die zugrunde liegende Richtlinienkategorie an.

Fehler

Eine Komprimierungsanfrage oder eine Anfrage, die einen Block enthält, kann auch vollständig fehlschlagen. Die meisten 400-Fehler haben eine Meldung, die angibt, was entfernt oder erneut gesendet werden muss. Einige enthalten zusätzlich einen error.details.error_code, der mit compaction_ beginnt. Parameterfehler, etwa ein Feld, das nicht mit compaction kombiniert werden kann, enthalten nur die Meldung.

Komprimierungsnutzung zählen

Der Zusammenfassungsaufruf wird wie jede andere Anfrage abgerechnet und unterliegt denselben Ratenlimits, und usage.iterations weist ihn als compaction-Eintrag aus. Die input_tokens und output_tokens auf oberster Ebene sind null, weil keine Antwort generiert wurde. Um zu zählen, was eine Unterhaltung verbraucht hat, summiere über usage.iterations, nicht über die Felder auf oberster Ebene. Das Zurücksenden eines Blocks bei späteren Anfragen verursacht keine zusätzlichen Komprimierungskosten.

Du hast jetzt eine funktionierende Schleife, die eine Unterhaltung komprimiert und eine fehlende Zusammenfassung behandelt. Zwei Seiten verändern, wie sie abläuft, und du kannst sie kombinieren: Komprimierung, die die letzten Turns beibehält behält die letzten Turns wortwörtlich bei, und Komprimierung im Hintergrund lässt die Unterhaltung weiterlaufen, während die Zusammenfassung geschrieben wird. Komprimierung und beibehaltenes Denken ist relevant, wenn du Thinking-Blöcke zurücksendest und eines von beiden tust.

Einschränkungen und Wechselwirkungen mit anderen Funktionen

• Schwellenwert-Komprimierung und Kontextbearbeitung. Du kannst compaction und context_management nicht in derselben Anfrage senden. Die Schwellenwert-Komprimierung (compact_20260112) kann nicht bei einer Anfrage ausgeführt werden, die einen signierten Block enthält.
• Prompt-Caching. cache_control auf dem Block setzt einen Breakpoint nach der Zusammenfassung.
• System-Nachrichten und Tool-Änderungen mitten in der Unterhaltung. role: "system"-Nachrichten innerhalb des zusammengefassten Bereichs werden ebenfalls zusammengefasst, sodass ihre Textanweisungen nicht mehr gelten, sobald der Block sie ersetzt. Wenn eine Anweisung weiterhin wichtig ist, formuliere sie erneut in einer role: "system"-Nachricht. Sende diese Nachricht direkt nach deinem nächsten neuen user-Turn und behalte sie von da an in deinem Verlauf. Für Tool-Änderungen und dafür, wo diese Nachricht hingehört, wenn du Turns nach dem Block behältst, siehe System-Prompt oder Tools ändern.
• Task-Budgets. Sende den remaining-Wert eines Task-Budgets (output_config.task_budget.remaining) nicht zusammen mit compaction oder bei Anfragen, die den Block enthalten. Andernfalls wird ein 400-Fehler zurückgegeben.
• Token-Zählung. Der Endpunkt für Token-Zählung ignoriert den Parameter compaction.
• Inhalte, die die Zusammenfassung nicht übernehmen kann. Bilder, Dokumente, container_upload-Blöcke und abgerufene URLs innerhalb der zusammengefassten Nachrichten sind verloren, sobald der Block sie ersetzt. Formuliere alles, was ein späterer Turn noch benötigt, erneut oder lade es erneut hoch.

Compatibility