Compaction et réflexion préservée

Ignorez cette page, sauf si vous renvoyez des « thinking blocks » (blocs de réflexion) à un modèle doté de la « preserved thinking » (réflexion préservée) et que vous conservez des tours après le bloc de compaction. Les « kept turns » (tours conservés) sont les tours qui suivent le bloc. Il peut s'agir de tours récents que vous avez exclus de la requête de compaction, comme dans Compaction qui conserve les tours récents. Il peut aussi s'agir de tours arrivés pendant la rédaction du résumé, comme dans Compaction en arrière-plan.

Les modèles dotés de la réflexion préservée vérifient les blocs de réflexion antérieurs par rapport à la conversation qui les a produits. Un résumé remplace une partie de cette conversation. La vérification accepte toutefois cette substitution lorsque c'est l'API qui a rédigé le résumé, de sorte que la réflexion des tours conservés peut rester valide.

Conditions pour que la réflexion conservée reste valide

Les blocs de réflexion des tours conservés restent valides tant que toutes ces conditions sont remplies :

• La requête de compaction s'exécute sur un modèle doté de la réflexion préservée. Cette condition couvre chaque requête de compaction effectuée depuis la production d'un bloc de réflexion, et pas seulement la plus récente. Pour la remplir, vous pouvez par exemple envoyer chaque requête de compaction au modèle qu'utilise la conversation.
• Les tours conservés suivent directement les messages résumés, et vous les envoyez sans modification. Envoyez chaque message conservé exactement tel qu'il figure dans votre historique. N'omettez et n'ajoutez aucun message entre le dernier message résumé et le premier message conservé. Le premier message conservé doit également avoir un rôle différent de celui du dernier message résumé. Il ne peut pas non plus s'agir d'un message role: "system" en cours de conversation. Sinon, l'API le fusionne avec le dernier message résumé. Pour obtenir un premier message conservé correct, vous pouvez par exemple compacter exactement les messages d'une requête que vous avez déjà envoyée. Les tours conservés commencent alors par la réponse de Claude à cette requête.
• system et les tools non marqués defer_loading: true ne changent pas. Ils sont identiques dans la requête de compaction et dans les requêtes qui ont produit la réflexion conservée, et ils restent identiques dans les requêtes suivantes. La section Modifier l'invite système ou les outils explique comment les modifier en toute sécurité.

Si une condition n'est pas remplie, rien n'échoue lors de la compaction, et l'API accepte le bloc dans les requêtes ultérieures dans tous les cas. L'échec survient lors de la première requête ultérieure qui envoie la réflexion conservée là où l'API applique la vérification. Par défaut, il s'agit d'une erreur 400. Si la requête définit thinking.block_binding.prefix_mismatch_behavior sur "drop_block", les blocs de réflexion sont supprimés. Dans l'API Message Batches, un élément qui laisse ce champ non défini n'échoue pas : là où la vérification s'applique par défaut, l'API supprime plutôt les blocs. La section Ce que fait l'API d'un bloc invalide décrit les deux résultats, et la section Quand l'API applique la vérification indique quelles requêtes sont vérifiées.

Compacter à nouveau sans invalider la réflexion antérieure

Vous pouvez compacter à nouveau tout en conservant des tours. Le nouveau bloc couvre l'ancien résumé et chaque message qui le suit dans la requête de compaction. Tous les tours que vous excluez de cette requête deviennent des tours conservés du nouveau bloc.

La première des conditions pour que la réflexion conservée reste valide prend en compte chaque compaction effectuée depuis la production d'un bloc de réflexion. Ainsi, pour un tour que vous conservez à travers deux compactions, les deux doivent s'être exécutées sur un modèle doté de la réflexion préservée.

Les compactions antérieures à la production d'un bloc de réflexion ne sont pas prises en compte pour ce bloc. La réflexion produite après la mise en place d'un bloc de compaction est liée à ce bloc. Elle reste valide à travers les compactions ultérieures qui remplissent les conditions.

Modifier l'invite système ou les outils

Une requête ultérieure peut utiliser un system, des tools ou un modèle différents de ceux de la requête de compaction, et l'API accepte toujours le bloc. Un tel changement peut invalider la réflexion des tours conservés, mais il n'a aucun autre effet.

Pour modifier system ou tools sans invalider la réflexion conservée, compactez d'abord toute la conversation, afin qu'aucun tour ne soit conservé. Modifiez-les ensuite dans la requête suivante.

Pour ajouter une instruction ou modifier les outils disponibles sans toucher à system ni à tools, ajoutez la modification à la fin de messages, comme décrit dans Effectuer des changements sans modifier le préfixe.

Les messages système en cours de conversation situés dans les tours résumés sont également résumés. Leurs instructions textuelles cessent donc de s'appliquer après la substitution. Pour maintenir l'un de ces messages en vigueur, énoncez-le à nouveau dans un message role: "system" placé directement après le premier nouveau tour user qui suit les tours conservés. Les modifications d'outils effectuées dans ces tours sont reportées automatiquement lorsque la requête de compaction comporte également inline-tools-2026-09-15. Le bloc renvoyé enregistre alors leur effet net dans son champ tool_changes : renvoyez donc le bloc sans le modifier. Si le bloc n'a pas de champ tool_changes, énoncez à nouveau ces modifications d'outils de la même manière. Un message système placé entre le bloc et les tours conservés invalide leur réflexion.

Vérifier que la réflexion conservée est restée valide

La réponse de compaction n'indique pas si la réflexion conservée reste valide. C'est la première requête après la substitution qui le révèle. Pour le vérifier dans vos tests :

1. Menez une courte conversation avec la réflexion activée. Utilisez un modèle sur lequel l'API exécute la vérification (voir Quand l'API applique la vérification), et utilisez-le pour chaque étape. En effet, un modèle qui ne peut pas lire un bloc de réflexion le supprime sans renvoyer d'erreur.
2. Compactez les tours les plus anciens, et conservez au moins un tour qui contient un bloc de réflexion.
3. Envoyez la requête suivante en plaçant le bloc en premier, puis le tour conservé, puis un nouveau message user. Définissez thinking.block_binding.prefix_mismatch_behavior sur "error".
4. Lisez le résultat. Une réponse 200 dont le tableau input_transformations est vide signifie qu'aucun bloc de réflexion n'a échoué à la vérification ni n'a été supprimé. Une erreur 400 indiquant que le bloc est lié à une conversation différente signifie qu'au moins un bloc a échoué. Le message commence par le chemin du premier bloc en échec, et la section Ce que fait l'API d'un bloc invalide le présente en entier.

Le champ prefix_mismatch_behavior nécessite l'en-tête bêta thinking-binding-controls-2026-08-01 en plus de l'en-tête bêta compact-2026-09-04. Sur les comptes où la vérification n'est pas activée par défaut, définir ce champ active également la vérification pour la requête.

Le programme suivant exécute les quatre étapes. Il affiche le nombre de blocs de réflexion que contient le tour conservé et le nombre d'entrées de input_transformations. Si ce tableau ne contient aucune entrée, la réflexion conservée est restée valide :

from anthropic.types.beta import BetaMessageParam, BetaThinkingConfigParam

client = anthropic.Anthropic()

# Claude Fable 5.1 est le premier modèle qui vérifie la réflexion renvoyée par rapport à la conversation.
MODEL = "claude-fable-5-1"
BETAS = ["compact-2026-09-04", "thinking-binding-controls-2026-08-01"]
SYSTEM = "You help plan a recipe app's release. Keep answers short."
# Avec "error", un bloc de réflexion qui échoue à la vérification fait échouer la requête avec une erreur 400.
THINKING: BetaThinkingConfigParam = {
    "type": "adaptive",
    "block_binding": {"prefix_mismatch_behavior": "error"},
}

# 1. Menez une courte conversation avec la réflexion activée.
history: list[BetaMessageParam] = [
    {"role": "user", "content": "What are the main entities in the app's data model?"}
]
first = client.beta.messages.create(
    model=MODEL,
    max_tokens=8192,
    system=SYSTEM,
    betas=BETAS,
    thinking=THINKING,
    messages=history,
)
history += [
    {"role": "assistant", "content": first.content},
    {
        "role": "user",
        "content": "Testing starts on Tuesday, March 3, 2026, takes 10 weekdays, and pauses on March 9 and March 16. On which date does it end?",
    },
]
second = client.beta.messages.create(
    model=MODEL,
    max_tokens=8192,
    system=SYSTEM,
    betas=BETAS,
    thinking=THINKING,
    messages=history,
)
history.append({"role": "assistant", "content": second.content})
thinking_blocks = sum(block.type == "thinking" for block in second.content)
print(f"Thinking blocks in the kept turn: {thinking_blocks}")

# 2. Résumez le premier tour. Le deuxième tour reste hors de la requête.
summary = client.beta.messages.create(
    model=MODEL,
    max_tokens=4096,
    system=SYSTEM,
    betas=BETAS,
    thinking=THINKING,
    messages=history[:2],
    compaction={"type": "summarize"},
)
if summary.stop_reason != "compaction":
    raise SystemExit(f"No summary: {summary.stop_reason}")

# 3. Placez le bloc devant le tour conservé et posez la question suivante.
history = [
    {"role": "assistant", "content": summary.content},
    *history[2:],
    {"role": "user", "content": "Which day should the release go out?"},
]
third = client.beta.messages.create(
    model=MODEL,
    max_tokens=8192,
    system=SYSTEM,
    betas=BETAS,
    thinking=THINKING,
    messages=history,
)

# 4. Un code 200 sans bloc supprimé signifie que la réflexion conservée a été acceptée.
print(f"Dropped thinking blocks: {len(third.input_transformations)}")

Thinking blocks in the kept turn: 1
Dropped thinking blocks: 0

En production, "drop_block" permet aux requêtes de continuer à réussir lorsqu'une condition n'est pas remplie. Chaque bloc supprimé est alors signalé dans input_transformations avec reason: "prefix_binding_mismatch". Une entrée dont le path se situe dans un tour conservé signifie que la réflexion de ce tour n'est pas restée valide. La section Ce que fait l'API d'un bloc invalide décrit ce qui est supprimé et explique comment configurer une alerte à ce sujet.

Compatibility