Präfixprüfungen bei Thinking-Blöcken

Jede Anfrage, die „thinking blocks“ (Thinking-Blöcke) an ein Modell mit „preserved thinking“ (bewahrtes Nachdenken) zurücksendet, durchläuft einen „prefix check“ (Präfixprüfung). Eine Präfixprüfung schlägt fehl, wenn sich system, tools oder eine frühere Nachricht geändert hat, nachdem Claude einen Block erzeugt hat. Sie schlägt auch fehl, wenn ein Thinking-Block zwischen anderen weggelassen oder verschoben wurde.

Schlägt die Präfixprüfung fehl, kann das zu einem 400-Fehler führen oder auch nicht, je nach Modell, also behandle beide Fälle.

Wen die Präfixprüfung betrifft

Du musst nichts ändern, wenn einer dieser Punkte zutrifft:

• Claude Code, claude.ai oder Claude Managed Agents verwaltet deinen Konversationsverlauf.
• Das Claude Agent SDK verwaltet den Verlauf, und der System-Prompt, den du dem SDK übergibst, bleibt gleich.
• Dein Code folgt den drei Gewohnheiten einer „append-only“ (nur anhängenden) Integration, und nichts schreibt seine Anfragen unterwegs um.
• Du rufst kein Modell mit bewahrtem Nachdenken auf.

Wenn deine Anfragen durch eine Bibliothek, einen Proxy oder ein Gateway laufen, vergleiche, was diese sendet, mit dem, was du gesendet hast. Wenn du selbst eines betreibst, sieh unter Bibliotheken, Proxys und Gateways nach, was du durchreichen solltest.

Was gleich bleiben muss, und warum

Mach deine Integration append-only. Drei Gewohnheiten erreichen das:

1. Sende jeden Assistant-Turn genau so zurück, wie die API ihn zurückgegeben hat, einschließlich Thinking-Blöcken, deren Text leer ist.
2. Erstelle system und tools einmal pro Konversation und sende jedes Mal diese Kopie.
3. Setze jede Aktualisierung in eine neue Nachricht am Ende und lass sie dort.

Das Reasoning jedes Thinking-Blocks bezieht sich genau auf das, was vor ihm kam: system, tools und jede frühere Nachricht. Dieser Inhalt ist das Präfix des Blocks, und er ist das, was die Präfixprüfung vergleicht.

Die Präfixprüfung ähnelt dem Prompt-Caching, nur dass eine Änderung das Nachdenken danach ungültig macht, statt nur den Cache zu verfehlen.

Nimm eine App, die das heutige Datum in ihren System-Prompt schreibt. Um Mitternacht ändert sich das Datum und damit auch das Präfix des Nachdenkens, das bereits in der Konversation steht. Dieses Nachdenken wird ungültig, und die nächste Anfrage kann fehlschlagen. Eine append-only-App lässt den System-Prompt, wie er war, und nennt das neue Datum in einer Nachricht am Ende.

Eine Änderung macht nur das Nachdenken ungültig, das ihr bereits folgt. Das Nachdenken davor und das Nachdenken, das Claude danach erzeugt, bleiben gültig.

Wenn dein Code den System-Prompt, die Tools oder den Verlauf ändert

Andere Ursachen, etwa das Überspringen von Thinking-Blöcken mit leerem Text oder das Neuaufbauen einer gespeicherten Konversation, haben eigene Lösungen: siehe Tools oder Anweisungen ändern, ohne dass die Präfixprüfung fehlschlägt. Um deine Ursache zu finden, lass einen Agenten deinen Code prüfen.

Was jedes Modell tut, wenn die Präfixprüfung fehlschlägt

In der Claude API und auf einigen Cloud-Plattformen hängt das Ergebnis einer fehlgeschlagenen Präfixprüfung, wenn prefix_mismatch_behavior nicht gesetzt ist, vom Modell ab:

Wo die Tabelle „Möglicher 400-Fehler“ angibt, gibt es zwei Fälle: Eine Anfrage, bei der die Präfixprüfung fehlschlägt, erhält möglicherweise einen 400-Fehler oder keinen Fehler. Wenn kein Fehler zurückgegeben wird, erreichen die Blöcke, bei denen die Präfixprüfung fehlschlägt, das Modell. Claude liest sie wie jede andere Eingabe, sie werden dir in Rechnung gestellt, und Claude arbeitet mit Reasoning über Inhalte, die sich inzwischen geändert haben.

Bei diesen Modellen kannst du prüfen, welchen Fall eine Anfrage erhält, solltest aber beide Fälle behandeln.

Message-Batches-Elemente, die prefix_mismatch_behavior nicht setzen, erhalten keinen Fehler, und die API kann die Blöcke, bei denen die Präfixprüfung fehlschlägt, weglassen.

Beide Fälle behandeln

Für ein einheitliches Ergebnis bei jeder Anfrage mach deine Integration append-only oder setze prefix_mismatch_behavior. Andernfalls muss dein Code beide Verhaltensweisen behandeln.

• Append-only: Mit den drei Gewohnheiten führt dein Code nicht dazu, dass bei einer Anfrage die Präfixprüfung fehlschlägt.
• Die Einstellung: Mit "error" bei jeder Anfrage ist jede fehlgeschlagene Präfixprüfung ein 400-Fehler, und du fängst ihn im Code ab.
• Beide Verhaltensweisen: Wenn du die Einstellung nicht setzt, fang den 400-Fehler ab und achte auf Nachdenken, bei dem die Präfixprüfung fehlgeschlagen ist und das Claude erreicht hat.

Sende nach einem 400-Fehler "drop_block" bei den späteren Anfragen dieser Konversation, um sie wiederherzustellen. Das hat seinen Preis: siehe Was das Weglassen von Nachdenken kostet. Sende es nicht bei all deinen Konversationen, um Fehler zu verbergen.

Technische Details

Wie die Präfixprüfung funktioniert

Die Modelle mit bewahrtem Nachdenken speichern einen Fingerabdruck des Präfixes jedes Thinking-Blocks in seiner signature. Die API-Referenz nennt die Präfixprüfung die Konversationsprüfung, und der 400-Fehler besagt, dass ein Block, bei dem die Präfixprüfung fehlschlägt, is bound to a different conversation.

Welche Modelle die Präfixprüfung ausführen

Die Präfixprüfung läuft in der Claude API und auf einigen Cloud-Plattformen. Sie prüft Thinking-Blöcke, die ein Modell mit bewahrtem Nachdenken erzeugt hat, bei Anfragen an eines dieser Modelle. In der Claude API führen andere Modelle, etwa Claude Opus 5, sie nicht aus, und sie deckt deren Blöcke nicht ab.

Was als Änderung zählt

• Jeder Block wird mit seinem eigenen Eintrag verglichen. Die API vergleicht, was in dieser Anfrage vor einem Block steht, mit dem, was seine Signatur festgehalten hat, als Claude ihn erzeugt hat. Deine letzte Anfrage spielt keine Rolle. Die Präfixprüfung betrachtet nur Inhalte, nicht Sitzungen, IDs oder Benutzer. Derselbe Inhalt in einer neuen Anfrage oder einem Fork besteht sie.
• Die Präfixprüfung vergleicht, was du gesendet hast, nicht, was Claude gelesen hat. Komprimierung bei einem Token-Schwellenwert und Context Editing ändern nur, was Claude liest, daher zählen sie nie. Nach einem Komprimierungsblock mit Schwellenwert vergleicht die API nur die Nachrichten ab diesem Block sowie system und tools. Komprimierung auf Anfrage hat eigene Bedingungen: siehe Bedingungen, unter denen beibehaltenes Nachdenken gültig bleibt. Für eine per URL gesendete Datei und, in der Claude API, eine MCP-Tool-Liste vergleicht die API stattdessen, was sie abgerufen hat.
• Das Nachdenken, das du sendest, muss eine ununterbrochene Folge sein. Thinking-Blöcke werden nicht als Inhalt verglichen. Aber jeder, den du sendest, außer dem ersten, muss denselben vorherigen Thinking-Block haben wie zu dem Zeitpunkt, als Claude ihn erzeugt hat. Du kannst also den ältesten, den neuesten oder alle weglassen, aber nicht einen dazwischen.

Eine Änderung kann so klein sein wie ein einzelnes Wort einer Tool-Beschreibung. Das Ändern, Einfügen, Verschieben oder Löschen einer früheren Nachricht zählt, unabhängig von ihrer Rolle. Ebenso das Ändern von Text vor einem Thinking-Block in dessen eigener Nachricht.

Was nicht zählt

prefix_mismatch_behavior setzen

Der Beta-Header thinking-binding-controls-2026-08-01 fügt die Einstellung thinking.block_binding.prefix_mismatch_behavior und das Array input_transformations der Antwort hinzu.

Blöcke, bei denen die Präfixprüfung fehlschlägt, bleiben bei jeder späteren Anfrage, die sie sendet, ungültig, solange die Änderung besteht. Die Einstellung wirkt auf die eine Anfrage, die sie enthält. Bei ausgeschaltetem Nachdenken ("disabled" oder "between_tools") ist das Senden der Einstellung bei jedem Modell ein 400-Fehler.

Die folgende Anfrage setzt prefix_mismatch_behavior auf "drop_block". Bei einem ersten Turn gibt es kein Nachdenken zum Zurücksenden, daher kommt input_transformations leer zurück:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "block_binding": {"prefix_mismatch_behavior": "drop_block"},
    },
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
    betas=["thinking-binding-controls-2026-08-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print(f"Input transformations: {len(response.input_transformations or [])}")

Produktionsverkehr beobachten

Wenn prefix_mismatch_behavior nicht gesetzt ist, erhält eine Anfrage, bei der die Präfixprüfung fehlschlägt, bei einigen Modellen möglicherweise keinen Fehler. Die Thinking-Blöcke, bei denen die Präfixprüfung fehlgeschlagen ist, erreichen dann das Modell. Um diese Blöcke im Produktionsverkehr zu finden, sende den Beta-Header thinking-binding-controls-2026-08-01, setze die Einstellung nicht und protokolliere das Array input_transformations jeder Antwort. Der Header fügt dieses Array hinzu und ändert nicht, was das Modell erhält.

Jeder dieser Blöcke erhält einen eigenen thinking_mismatch_allowed-Eintrag in diesem Array. Ein Eintrag sieht so aus:

{
  "input_transformations": [
    {
      "type": "thinking_mismatch_allowed",
      "path": "messages.1.content.0",
      "reason": "prefix_binding_mismatch"
    }
  ]
}

Um die Änderung zu finden, siehe Finde heraus, was dein Code geändert hat.

Prüfen, welchen Fall du erhältst

Bei einigen Modellen erhält eine Anfrage, bei der die Präfixprüfung fehlschlägt, möglicherweise den 400-Fehler oder keinen Fehler. Dieser Test zeigt, welchen Fall eine Anfrage erhält:

1. Nimm eine Konversation, die einen Thinking-Block von einem dieser Modelle enthält. Ändere den System-Prompt (system) oder füge ihn hinzu. Bei dem Block schlägt dann die Präfixprüfung fehl, weil sich der System-Prompt geändert hat, nachdem Claude den Block erzeugt hat.
2. Sende sie mit dem Beta-Header thinking-binding-controls-2026-08-01 an dasselbe Modell und setze prefix_mismatch_behavior nicht.

Die Antwort ist eine der folgenden:

• Ein 400-Fehler, der bound to a different conversation angibt: Die Anfrage hat den 400-Fehler erhalten.
• Eine 200-Antwort, deren Array input_transformations thinking_mismatch_allowed-Einträge enthält: Die Anfrage hat keinen Fehler erhalten. Jeder Eintrag nennt einen Thinking-Block, bei dem die Präfixprüfung fehlgeschlagen ist und der Claude erreicht hat.
• Eine 200-Antwort, deren Array input_transformations leer ist: Bei keinem Block ist die Präfixprüfung fehlgeschlagen, daher zeigt der Test nichts. Prüfe, ob die Konversation einen Thinking-Block von diesem Modell enthält.

Das Ergebnis beschreibt diese eine Anfrage und verspricht nichts über spätere, also schreib deinen Code so, dass er beide Fälle behandeln kann.

Nächste Schritte