Blog • AI / API

Claude API 2026: Was ist Conversation Compaction? Wie speichert ein AI Agent langen Kontext und den komprimierten Zustand als JSON?

Je länger ein Agent läuft, desto länger wird das Messages-Array. Tool-Ergebnisse, thinking-Blöcke und Hin und Her mit dem User füllen das Kontextfenster. 2026 hat die Messages API daraus eine offizielle Fähigkeit gemacht: Conversation Compaction.

Compaction ist keine Zusammenfassung, die Sie auf dem Client schreiben und zurückkleben. Die API stellt einen type: "compaction"-JSON-Block aus. Die nächste Anfrage muss diesen Block unverändert in messages zurücklegen, sonst läuft die Session nicht vom komprimierten Zustand weiter.

Dieser Artikel behandelt:

• Welche Beta Schwellenwert-Kompression und die On-Demand-Kompression vom September jeweils nutzen
• Wie messages vor und nach der Kompression aussieht
• Welche Felder Sie speichern müssen, sonst lässt sich die Session nicht wiederherstellen
• Wie das JSON bei Hintergrund-Kompression und beim Behalten der letzten Turns getauscht wird
• Wie Sie Position und Felder eines Blocks in JSONNote prüfen

Welche Spanne Compaction wirklich komprimiert

Die offizielle Linie ist klar: serverseitige Kompression ist der empfohlene Weg für lange Gespräche und Agent-Workflows. Sie müssen auf dem Client keinen Zusammenfassungscode schreiben. Füllt das Fenster mit altem Inhalt, sinkt die Antwortqualität. Compaction tauscht früheren Inhalt gegen eine Zusammenfassung, damit der nützliche Kontext weiterlaufen kann. Siehe

Claude API Compaction.

Ist Schwellenwert-Kompression an, macht die API vier Schritte: Input-Tokens treffen den Trigger; sie schreibt eine Zusammenfassung; sie gibt einen compaction-Block aus; sie setzt die Antwort auf dem komprimierten Kontext fort. Wenn Sie das nächste Mal die volle Assistant-Antwort an messages anhängen, verwirft die API alles vor diesem Block und macht bei der Zusammenfassung weiter.

Es ist verlustbehaftet. Genutzte Tool-Argumente, der genaue Wortlaut und frühes thinking bleiben nicht Wort für Wort. Was bleibt, sind Ziele, Entscheidungen und Fakten, die Sie noch brauchen. Das ist nicht dasselbe wie „das ganze messages-Array in eine Datenbank legen“. Wie Kontext in einem Agent-Stack wächst: siehe

2026 AI-Agent-Stack.

Zwei Wege: Schwellenwert-Kompression und On-Demand-Kompression

2026 gibt es zwei Betas. Mischen Sie sie nicht in derselben Anfrage. Die Doku sagt: der Parameter compaction darf nicht zusammen mit context_management gesendet werden.

Der Trigger der Schwellenwert-Kompression ist standardmäßig input_tokens 150000, Minimum 50000. Optional pause_after_compaction: nach der Zusammenfassung hält sie zuerst an, damit Sie die letzten Turns oder Anweisungsnachrichten hinter den Block setzen und dann weiter generieren können. Ein eigenes instructions ersetzt den Standard-Zusammenfassungsprompt vollständig, bis zu 16384 Zeichen.

On-Demand-Kompression ist der Kern der September-Linie. Sie entscheiden, wann komprimiert wird; die summarize-Anfrage kann im Hintergrund laufen, während das Gespräch die volle Historie behält; Sie können die letzten Turns auch im Original hinter der Zusammenfassung lassen. Der signierte Block muss ganz vorn in messages sitzen. Nachrichten, die zusammengefasst wurden, müssen vor dem Block weg, sonst gibt es einen 400 namens compaction_block_misplaced. Bedrock und Google Cloud haben den On-Demand-Weg nicht.

Messages-JSON vor und nach der Kompression

Zuerst der Zustand davor: normale user- / assistant-Turns.

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "messages": [
    {
      "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."
    },
    {
      "role": "user",
      "content": "Good. Now suggest field names for Recipe."
    }
  ],
  "compaction": { "type": "summarize" }
}

Die Antwort ist ein einzelner signierter compaction-Block; stop_reason ist compaction. In jeder späteren Anfrage muss dieser Block zuerst sitzen, gefolgt nur von Turns, die diese Zusammenfassung nicht verzehrt hat.

{
  "model": "claude-opus-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...",
          "signature": "EuYBCkQY..."
        }
      ]
    },
    {
      "role": "assistant",
      "content": "For Recipe, use title, description, servings..."
    },
    {
      "role": "user",
      "content": "Now do the same for Ingredient."
    }
  ]
}

Ein Schwellenwert-Block sitzt eher „in der Antwort“: das content-Array des Assistant beginnt mit compaction, dann text. Nach mehreren Kompressionen gilt der letzte Block; er ist der Endzustand des aktuellen Prompts. Sieht die API diesen Block, ignoriert sie Content-Blöcke davor. Sie können alles zurückgeben oder die alten Nachrichten selbst streichen und nur ab diesem Block senden.

Das SDK beschreibt encrypted_content als „opake Metadaten einer vorherigen Kompression; sie müssen unverändert round-triped werden.“ Auf dem Client nicht zerlegen und nicht als Zusammenfassungsbody zeigen. Ist content eines fehlgeschlagenen Blocks null, behandelt der Server das als No-Op. Sie können ihn trotzdem zurücksenden, er zählt aber nicht als gültige Zusammenfassung.

Felder, die Sie speichern müssen, um eine Session wiederherzustellen

Startet der Agent neu, ist das messages im Speicher weg. Was Sie wiederherstellen, ist nicht „das ganze Chatlog vor der Kompression“. Es ist der Zustand, der nach der Kompression noch die nächste Anfrage tragen kann.

1. 1
   Der neueste compaction-Block

   Der ganze JSON-Block, einschließlich content, signature und encrypted_content. Bei mehreren behalten Sie nur den neuesten: die nächste Kompression frisst die alte Zusammenfassung und alles danach.

2. 2
   messages hinter dem Block

   user- / assistant-Turns, die diese Zusammenfassung nicht erfasst hat, in der Originalreihenfolge. Turns, die während der Hintergrund-Kompression nachgewachsen sind, sitzen ebenfalls hier.

3. 3
   Das damalige system und tools

   Bei On-Demand-Kompression muss die summarize-Anfrage dasselbe system und tools tragen wie der Rest des Gesprächs. Bei Modellen, die thinking behalten, hängt die Gültigkeit des thinking hinter dem Block davon ab, ob diese beiden geändert wurden und ob der Tail direkt an den zusammengefassten Nachrichten sitzt.

4. 4
   Auf welcher Beta Sie sind

   Schwellenwert-Kompression sendet weiter compact-2026-01-12. Für einen On-Demand-Block muss jede spätere Anfrage noch compact-2026-09-04 senden. Ist der Header falsch, wird der Block möglicherweise nicht erkannt.

{
  "beta": "compact-2026-09-04",
  "model": "claude-opus-5",
  "system": "You are a coding agent.",
  "tools": [],
  "compaction_block": {
    "type": "compaction",
    "content": "Summary of the conversation: ...",
    "signature": "EuYBCkQY...",
    "encrypted_content": "..."
  },
  "tail": [
    {
      "role": "assistant",
      "content": "For Recipe, use title, description..."
    },
    {
      "role": "user",
      "content": "Now do the same for Ingredient."
    }
  ]
}

Beim Neuaufbau der Anfrage setzen Sie in messages[0] den Assistant, der diesen Block trägt (oder den Block in den ersten content der ersten Nachricht), und hängen dann tail an. Schieben Sie keine alten user-Nachrichten von vor der Kompression wieder vor den Block.

Das ist nicht dieselbe Schicht wie die Rechtebewertung. Die entscheidet, ob ein Tool Call laufen darf. Hier geht es darum, ob der Zustand nach dem Verzehr des Fensters noch da ist. Zu Rechten siehe

Wie Claude Managed Agents entscheiden, ob ein Tool Call erlaubt ist.

Wie Claude an KI-Forschungsworkflows teilnimmt.

Tausch bei Hintergrund-Kompression und wenn Sie einen Tail behalten

Eine On-Demand-Anfrage fasst nur die Nachrichten zusammen, die sie bekommen hat. Sie können also nur die alten Turns zum Komprimieren schicken, die letzten Turns im Original auf dem Client behalten und den Block davor setzen, wenn er zurückkommt. Offiziell heißt das keep-tail.

Hintergrund-Kompression (async) geht weiter: während die Zusammenfassung noch läuft, nutzt das Gespräch die volle Historie. Kommt sie zurück, dürfen Sie die ganze Historie nicht durch einen Block ersetzen. Sie streichen vorn nur die Nachrichten, die Sie zum Komprimieren geschickt haben, setzen die zurückgegebene assistant-Nachricht ein und lassen die danach nachgewachsenen Turns unverändert.

if response.stop_reason == "compaction":
    compaction_message = {
        "role": "assistant",
        "content": response.content,
    }
    history = [compaction_message] + history[sent_count:]
# sent_count = number of messages sent in the compaction request

Ändern Sie in der Mitte keine Nachrichten, die schon in der Historie stehen. Der Tausch muss in der ersten Anfrage nach Ankunft des Blocks passieren, damit thinking aus der Zusammenfassungszeit gültig bleibt. Kommt kein Block zurück, behalten Sie die volle Historie und versuchen es später erneut.

Schaltet Schwellenwert-Kompression pause_after_compaction ein, ist die Antwort oft nur dieser Block, und stop_reason ist ebenfalls compaction. Hängen Sie die Original-Turns, die Sie behalten wollen, hinter den Block und senden Sie die nächste Anfrage. Hinweis: Bei Claude Fable 5.1 müssen Sie, wenn Sie alte assistant-Turns hinter den Block setzen, deren thinking / redacted_thinking entfernen oder thinking-binding-controls-2026-08-01 mitsenden und prefix_mismatch_behavior: "drop_block" setzen, sonst droht ein 400. Diese thinking-Blöcke entstanden gegen die volle Historie und passen nicht zum komprimierten Gespräch.

Wie es sich mit dem Prompt-Cache stapelt

Kompression und Prompt-Caching können zusammenlaufen. Sie können cache_control: {"type":"ephemeral"} auf den compaction-Block setzen, damit die Zusammenfassung allein in den Cache geht. Setzen Sie am Ende des System-Prompts einen weiteren Breakpoint. Tritt Kompression ein, kann der Cache des System-Prompts weiter treffen, und nur das Zusammenfassungssegment wird neu geschrieben.

Bei der Abrechnung nicht nur das Top-Level-usage ansehen. Tokens aus Kompressionsiterationen können in usage.iterations stehen. Auf der Persistenzseite zählen weiter nur Block und Tail. usage ist kein Vertrag zum Wiederherstellen einer Session.

Block und Historie in JSONNote prüfen

Die JSON-Größe vor und nach der Kompression unterscheidet sich stark, und die Felder lassen sich nicht mit dem Auge scannen. Beim Debuggen prüfen Sie die Position, nicht den Stil.

1. 1
   Zuerst die gespeicherte Datei formatieren

   Legen Sie das Session-JSON in den JSON-Formatierer. Prüfen Sie, dass compaction_block.type compaction ist und signature noch da ist.

2. 2
   Dann die Form des Blocks prüfen

   Mit JSON Schema ein minimales Schema schreiben: type enumeriert nur compaction; content erlaubt string oder null; ist signature / encrypted_content vorhanden, als string behandeln. Leere Strings sind verboten.

3. 3
   messages vor und nach der Kompression vergleichen

   Mit JSON Diff sehen, welche Turns vorn aus der Queue sind und was hinter dem Block dazukam. Nach On-Demand-Kompression dürfen zusammengefasste user-Nachrichten nicht vor dem Block sitzen.

4. 4
   Signaturen beim Recap schwärzen

   Den Zusammenfassungsbody dürfen Menschen sehen. Signaturen und opake Felder vor dem Hash-Teilen schwärzen. Sie können eine Session fortsetzen. Nicht als normalen Text verschicken.

Häufige Fragen

Löscht Conversation Compaction das ganze Gespräch?

Nein. Die API ersetzt bereits komprimierte alte Nachrichten durch eine Zusammenfassung. Die sitzt in einem Content-Block mit type compaction. Diesen Block müssen Sie unverändert zurücksenden, sonst kann die Session nicht von der Zusammenfassung weiterlaufen.

Welches JSON müssen Sie mindestens speichern, um eine Session wiederherzustellen?

Mindestens den neuesten compaction-Block (einschließlich content, signature, encrypted_content), alle messages hinter dem Block sowie das damalige system und tools. Fehlt die Signatur oder ein opakes Feld, verbindet die nächste Anfrage nicht.

Worin unterscheiden sich Schwellenwert-Kompression und die On-Demand-Kompression vom September?

Schwellenwert-Kompression nutzt compact-2026-01-12 und feuert nach Tokenzahl in einer normalen Anfrage. On-Demand-Kompression nutzt compact-2026-09-04, sendet compaction: {type: summarize} allein und gibt einen signierten Block zurück, der ganz vorn in messages sitzen muss.

Kann ein selbst geschriebener Zusammenfassungstext einen compaction-Block ersetzen?

Nicht als derselbe Vertrag. Die Plattform erkennt den Block, den sie ausgestellt hat. Ein user-Text von Ihnen ist nur eine weitere Nachricht. Er hat keine signature und bringt die API nicht dazu, den alten Inhalt vor dem Block zu verwerfen.

Darf man den content eines compaction-Blocks ändern und zurückschicken?

Nicht ändern. Die offizielle Doku verlangt unverändertes Echo. Ein leerer String in content ist ungültig; content null heißt, die Kompression ist fehlgeschlagen, der Server behandelt das als No-Op. signature oder encrypted_content zu ändern lässt spätere Anfragen scheitern oder die Zusammenfassung fallen.

Kurzfassung

Conversation Compaction macht aus „das Fenster platzt gleich“ einen JSON-Block, den Sie zurücksenden können. Schwellenwert-Kompression läuft automatisch in einer normalen Anfrage. Die On-Demand-Kompression vom September lässt Sie entscheiden, wann komprimiert wird, ob es im Hintergrund laufen darf und ob die letzten Turns im Original bleiben.

Eine Session wiederherstellen hängt am neuesten compaction-Block plus dem Tail dahinter, nicht am vollen Text vor der Kompression. content, signature und encrypted_content unverändert speichern und unverändert senden. Sitzt der Block falsch, tut die API nicht so, als hätten Sie diese Historie noch.

Lesen Sie Block und Tail als zwei Verträge. Bei langen Aufgaben, die ein Mensch im Blick behalten muss, schreiben Sie die Entitäten, die bleiben müssen, und die offenen Fragen in die Zusammenfassungs-instructions. Bei einem Agent, der weniger unterbrochen werden soll, tauschen Sie den Block im Hintergrund per On-Demand-Kompression. Lassen Sie im Speicher nicht nur eine selbst geschriebene Notiz.

← Zurück zum Blog