MessagesGestion du contexte

Compaction

Compaction de contexte côté serveur pour gérer les longues conversations qui approchent des limites de la fenêtre de contexte.

Cette fonctionnalité est éligible à la Zero Data Retention (ZDR). Lorsque votre organisation dispose d'un accord ZDR, les données envoyées via cette fonctionnalité ne sont pas stockées après le retour de la réponse de l'API.

La compaction côté serveur est la stratégie recommandée pour gérer le contexte dans les conversations de longue durée et les workflows agentiques. Elle gère automatiquement le contexte, sans code de résumé côté client.

La « compaction » (compaction) étend la longueur effective du contexte pour les conversations et tâches de longue durée en résumant automatiquement le contexte plus ancien lorsque la limite de la « context window » (fenêtre de contexte) approche. Elle maintient également le contexte actif réduit : à mesure qu'une conversation s'allonge, la qualité des réponses se dégrade, donc la compaction remplace le contenu plus ancien par un résumé concis.

Pour une analyse plus approfondie des raisons pour lesquelles les contextes longs se dégradent et de la manière dont la compaction aide, consultez Effective context engineering.

Ceci est idéal pour :

Les conversations multi-tours basées sur le chat où vous souhaitez que les utilisateurs utilisent une même conversation pendant une longue période
Les prompts orientés tâches qui nécessitent beaucoup de travail de suivi (souvent de l'utilisation d'outils) susceptible de dépasser la fenêtre de contexte

La compaction est en version bêta. Incluez l'en-tête bêta compact-2026-01-12 dans vos requêtes API pour utiliser cette fonctionnalité.

Modèles pris en charge

La compaction est prise en charge sur les modèles suivants :

Claude Fable 5 (claude-fable-5)
Claude Mythos 5 (claude-mythos-5)
Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)

Fonctionnement de la compaction

Lorsque la compaction est activée, Claude résume automatiquement votre conversation lorsqu'elle atteint le seuil de tokens configuré. L'API :

Détecte lorsque les tokens d'entrée atteignent votre seuil de déclenchement spécifié.
Génère un résumé de la conversation actuelle.
Crée un bloc compaction contenant le résumé.
Poursuit la réponse avec le contexte compacté.

Lors des requêtes suivantes, ajoutez la réponse à vos messages. L'API supprime automatiquement tous les blocs de contenu antérieurs au bloc compaction, poursuivant la conversation à partir du résumé.

Flux de compaction : lorsque les tokens d'entrée atteignent le déclencheur, Claude écrit un résumé dans un bloc de compaction et continue

Utilisation de base

Activez la compaction en ajoutant la stratégie compact_20260112 à context_management.edits dans votre requête à l'API Messages.

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

# Ajoutez la réponse (y compris tout bloc de compactage) pour poursuivre la conversation
messages.append({"role": "assistant", "content": response.content})

Paramètres

Paramètre	Type	Valeur par défaut	Description
`type`	string	Obligatoire	Doit être `"compact_20260112"`
`trigger`	object	`{"type": "input_tokens", "value": 150000}`	Quand déclencher la compaction. `input_tokens` est le seul type de déclencheur pris en charge. `value` doit être d'au moins 50 000 tokens.
`pause_after_compaction`	boolean	`false`	Indique s'il faut mettre en pause après la génération du résumé de compaction
`instructions`	string	`null`	Prompt de résumé personnalisé. Remplace complètement le prompt par défaut lorsqu'il est fourni.

Configuration du déclencheur

Configurez le moment où la compaction se déclenche à l'aide du paramètre trigger :

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

Instructions de résumé personnalisées

Le prompt de résumé par défaut varie selon le modèle. Chaque prompt par défaut demande à Claude d'écrire un résumé à l'intérieur de balises <summary></summary> avec les informations nécessaires pour poursuivre la tâche dans une future fenêtre de contexte. Par exemple, certains modèles utilisent le prompt suivant :

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.

Vous pouvez fournir des instructions personnalisées via le paramètre instructions. Les instructions personnalisées ne complètent pas le prompt par défaut. Elles le remplacent complètement :

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

Mise en pause après la compaction

Utilisez pause_after_compaction pour mettre l'API en pause après la génération du résumé de compaction. Cela vous permet d'ajouter des blocs de contenu supplémentaires (comme la préservation de messages récents ou de messages spécifiques orientés instructions) avant que l'API ne poursuive avec la réponse.

Lorsque cette option est activée, l'API renvoie un message avec le stop_reason compaction après avoir généré le bloc de compaction :

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

# Vérifier si la compaction a déclenché une pause
if response.stop_reason == "compaction":
    # La réponse contient uniquement le bloc de compaction
    messages.append({"role": "assistant", "content": response.content})

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

Application d'un budget total de tokens

Lorsqu'un modèle travaille sur des tâches longues avec de nombreuses itérations d'utilisation d'outils, la consommation totale de tokens peut augmenter considérablement. Vous pouvez combiner pause_after_compaction avec un compteur de compactions pour estimer l'utilisation cumulée et conclure proprement la tâche une fois qu'un budget est atteint.

Cet exemple apparaît uniquement dans les langages des SDK : son intérêt réside dans la logique de suivi du budget autour de la requête. La requête brute combine le trigger de Configuration du déclencheur avec pause_after_compaction de Mise en pause après la compaction.

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

    # Estimer le total de tokens consommés ; inviter à conclure si le budget est dépassé
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

Travailler avec les blocs de compaction

Lorsque la compaction est déclenchée, l'API renvoie un bloc compaction au début de la réponse de l'assistant.

Une conversation de longue durée peut entraîner plusieurs compactions. Le dernier bloc de compaction reflète l'état final du prompt, remplaçant le contenu qui le précède par le résumé généré.

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..."
    }
  ]
}

Renvoyer les blocs de compaction

Vous devez renvoyer le bloc compaction à l'API lors des requêtes suivantes pour poursuivre la conversation avec le prompt raccourci. L'approche la plus simple consiste à ajouter l'intégralité du contenu de la réponse à vos messages :

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# Après avoir reçu une réponse contenant un bloc de compaction
messages.append({"role": "assistant", "content": response.content})

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

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

Lorsque l'API reçoit un bloc compaction, tous les blocs de contenu qui le précèdent sont ignorés. Vous pouvez soit :

Conserver les messages originaux dans votre liste et laisser l'API gérer la suppression du contenu compacté
Supprimer manuellement les messages compactés et n'inclure que le bloc de compaction et ce qui suit

Streaming

Le bloc de compaction est diffusé en streaming différemment des blocs de texte. Vous recevez un événement content_block_start, suivi d'un seul content_block_delta avec le contenu complet du résumé (sans streaming intermédiaire), puis un événement content_block_stop.

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

with client.beta.messages.stream(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    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 or '')} chars")
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

    # Obtenir le message final accumulé
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Mise en cache des prompts

La compaction fonctionne bien avec la mise en cache des prompts. Vous pouvez ajouter un point d'arrêt cache_control sur les blocs de compaction pour mettre en cache le contenu résumé.

{
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "[summary text]",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Based on our conversation..."
    }
  ]
}

Maximiser les correspondances de cache avec les invites système

Lorsque la compaction se produit, le résumé devient un nouveau contenu qui doit être écrit dans le cache. Sans points d'arrêt de cache supplémentaires, cela invaliderait également toute invite système mise en cache, nécessitant sa remise en cache en même temps que le résumé de compaction.

Pour maximiser les taux de correspondance du cache, ajoutez un point d'arrêt cache_control à la fin de votre invite système. Cela maintient l'invite système en cache séparément de la conversation, de sorte que lorsque la compaction se produit :

Le cache de l'invite système reste valide et est lu depuis le cache
Seul le résumé de compaction doit être écrit en tant que nouvelle entrée de cache

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

Cela maintient les longues invites système en cache à travers plusieurs événements de compaction tout au long d'une conversation.

Comprendre l'utilisation

La compaction nécessite une étape d'échantillonnage supplémentaire, qui contribue aux limites de débit et à la facturation. L'API renvoie des informations d'utilisation détaillées dans la réponse :

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
      }
    ]
  }
}

Le tableau iterations montre l'utilisation pour chaque itération d'échantillonnage. Lorsque la compaction se produit, vous verrez une itération compaction suivie de l'itération principale message. Les valeurs input_tokens et output_tokens de niveau supérieur correspondent exactement à l'itération message dans cet exemple, car il n'y a qu'une seule itération hors compaction. Les comptages de tokens de l'itération finale reflètent la taille effective du contexte après compaction.

Les valeurs input_tokens et output_tokens de niveau supérieur n'incluent pas l'utilisation de l'itération de compaction. Elles reflètent la somme de toutes les itérations hors compaction. Pour calculer le total des tokens consommés et facturés pour une requête, additionnez toutes les entrées du tableau usage.iterations.

Si vous vous appuyiez auparavant sur usage.input_tokens et usage.output_tokens pour le suivi des coûts ou l'audit, vous devrez mettre à jour votre logique de suivi pour agréger sur usage.iterations lorsque la compaction est activée. Avec la version bêta de la compaction activée, chaque réponse inclut usage.iterations, même si aucune compaction n'a eu lieu. Une entrée compaction n'apparaît que lorsqu'une nouvelle compaction est déclenchée pendant la requête. La réapplication d'un bloc compaction précédent n'entraîne aucun coût de compaction supplémentaire, et les champs d'utilisation de niveau supérieur restent exacts dans ce cas.

Combinaison avec d'autres fonctionnalités

Outils serveur

Lors de l'utilisation d'outils serveur (comme la recherche web), le déclencheur de compaction est vérifié au début de chaque itération d'échantillonnage. La compaction peut se produire plusieurs fois au sein d'une même requête en fonction de votre seuil de déclenchement et de la quantité de sortie générée.

Comptage de tokens

Le point de terminaison de comptage de tokens (/v1/messages/count_tokens) applique les blocs compaction existants dans votre prompt mais ne déclenche pas de nouvelles compactions. Utilisez-le pour vérifier votre nombre effectif de tokens après les compactions précédentes :

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

Exemples

Voici un exemple complet d'une conversation de longue durée avec compaction :

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

    # Ajouter la réponse (les blocs de compactage sont automatiquement inclus)
    messages.append({"role": "assistant", "content": response.content})

    # Retourner le contenu textuel
    return next(block.text for block in response.content if block.type == "text")


# Exécuter une longue 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"))
# Continuer à appeler chat() aussi longtemps que la conversation le nécessite

Voici un exemple qui utilise pause_after_compaction pour préserver l'échange précédent et le message utilisateur actuel (trois messages au total) mot pour mot au lieu de les résumer :

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

    # Vérifier si la compaction a eu lieu et s'est mise en pause
    if response.stop_reason == "compaction":
        # Récupérer le bloc de compaction depuis la réponse
        compaction_block = response.content[0]

        # Préserver l'échange précédent + le message utilisateur actuel (3 messages)
        # en les incluant après le bloc de compaction
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Construire la nouvelle liste de messages : compaction + messages préservés
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Poursuivre la requête avec le contexte compacté + les messages préservés
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-8",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Mettre à jour notre liste de messages pour refléter la compaction
        messages.clear()
        messages.extend(messages_after_compaction)

    # Ajouter la réponse finale
    messages.append({"role": "assistant", "content": response.content})

    # Retourner le contenu textuel
    return next(block.text for block in response.content if block.type == "text")


# Exécuter une longue 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"))
# Continuer à appeler chat() aussi longtemps que la conversation le nécessite

Limitations actuelles

Même modèle pour le résumé : Le modèle spécifié dans votre requête est utilisé pour le résumé. Il n'existe aucune option pour utiliser un modèle différent (par exemple, moins cher) pour le résumé.
La compaction peut échouer lorsque des outils sont définis : Lorsque votre requête inclut tools, le modèle appelle parfois un outil pendant l'étape interne de résumé au lieu d'écrire un résumé. Lorsque cela se produit, la réponse contient un bloc compaction avec content: null. Pour éviter cela, définissez instructions avec un prompt qui indique explicitement au modèle de ne pas appeler d'outils, par exemple :
```
Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only.
```

Étapes suivantes

Édition de contexte

Gérez automatiquement le contexte de la conversation à mesure qu'il s'étend grâce à l'édition de contexte.

Fenêtres de contexte

Découvrez les tailles de fenêtres de contexte et les stratégies de gestion.

Cookbook de compaction de mémoire de session

Explorez une implémentation pratique qui gère les conversations de longue durée avec une compaction instantanée de la mémoire de session en utilisant le threading en arrière-plan et la mise en cache des prompts.

Was this page helpful?

MessagesGestion du contexte

Compaction

Compaction de contexte côté serveur pour gérer les longues conversations qui approchent des limites de la fenêtre de contexte.

Pour une analyse plus approfondie des raisons pour lesquelles les contextes longs se dégradent et de la manière dont la compaction aide, consultez Effective context engineering.

Ceci est idéal pour :

Les conversations multi-tours basées sur le chat où vous souhaitez que les utilisateurs utilisent une même conversation pendant une longue période
Les prompts orientés tâches qui nécessitent beaucoup de travail de suivi (souvent de l'utilisation d'outils) susceptible de dépasser la fenêtre de contexte

La compaction est en version bêta. Incluez l'en-tête bêta compact-2026-01-12 dans vos requêtes API pour utiliser cette fonctionnalité.

Modèles pris en charge

La compaction est prise en charge sur les modèles suivants :

Claude Fable 5 (claude-fable-5)
Claude Mythos 5 (claude-mythos-5)
Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)

Fonctionnement de la compaction

Lorsque la compaction est activée, Claude résume automatiquement votre conversation lorsqu'elle atteint le seuil de tokens configuré. L'API :

Détecte lorsque les tokens d'entrée atteignent votre seuil de déclenchement spécifié.
Génère un résumé de la conversation actuelle.
Crée un bloc compaction contenant le résumé.
Poursuit la réponse avec le contexte compacté.

Utilisation de base

Activez la compaction en ajoutant la stratégie compact_20260112 à context_management.edits dans votre requête à l'API Messages.

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

# Ajoutez la réponse (y compris tout bloc de compactage) pour poursuivre la conversation
messages.append({"role": "assistant", "content": response.content})

Paramètres

Paramètre	Type	Valeur par défaut	Description
`type`	string	Obligatoire	Doit être `"compact_20260112"`
`trigger`	object	`{"type": "input_tokens", "value": 150000}`	Quand déclencher la compaction. `input_tokens` est le seul type de déclencheur pris en charge. `value` doit être d'au moins 50 000 tokens.
`pause_after_compaction`	boolean	`false`	Indique s'il faut mettre en pause après la génération du résumé de compaction
`instructions`	string	`null`	Prompt de résumé personnalisé. Remplace complètement le prompt par défaut lorsqu'il est fourni.

Configuration du déclencheur

Configurez le moment où la compaction se déclenche à l'aide du paramètre trigger :

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

Instructions de résumé personnalisées

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.

Vous pouvez fournir des instructions personnalisées via le paramètre instructions. Les instructions personnalisées ne complètent pas le prompt par défaut. Elles le remplacent complètement :

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

Mise en pause après la compaction

Lorsque cette option est activée, l'API renvoie un message avec le stop_reason compaction après avoir généré le bloc de compaction :

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

# Vérifier si la compaction a déclenché une pause
if response.stop_reason == "compaction":
    # La réponse contient uniquement le bloc de compaction
    messages.append({"role": "assistant", "content": response.content})

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

Application d'un budget total de tokens

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

    # Estimer le total de tokens consommés ; inviter à conclure si le budget est dépassé
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

Travailler avec les blocs de compaction

Lorsque la compaction est déclenchée, l'API renvoie un bloc compaction au début de la réponse de l'assistant.

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..."
    }
  ]
}

Renvoyer les blocs de compaction

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# Après avoir reçu une réponse contenant un bloc de compaction
messages.append({"role": "assistant", "content": response.content})

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

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

Lorsque l'API reçoit un bloc compaction, tous les blocs de contenu qui le précèdent sont ignorés. Vous pouvez soit :

Conserver les messages originaux dans votre liste et laisser l'API gérer la suppression du contenu compacté
Supprimer manuellement les messages compactés et n'inclure que le bloc de compaction et ce qui suit

Streaming

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

with client.beta.messages.stream(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    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 or '')} chars")
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

    # Obtenir le message final accumulé
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Mise en cache des prompts

La compaction fonctionne bien avec la mise en cache des prompts. Vous pouvez ajouter un point d'arrêt cache_control sur les blocs de compaction pour mettre en cache le contenu résumé.

{
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "[summary text]",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Based on our conversation..."
    }
  ]
}

Maximiser les correspondances de cache avec les invites système

Le cache de l'invite système reste valide et est lu depuis le cache
Seul le résumé de compaction doit être écrit en tant que nouvelle entrée de cache

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

Cela maintient les longues invites système en cache à travers plusieurs événements de compaction tout au long d'une conversation.

Comprendre l'utilisation

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
      }
    ]
  }
}

Combinaison avec d'autres fonctionnalités

Outils serveur

Comptage de tokens

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

Exemples

Voici un exemple complet d'une conversation de longue durée avec compaction :

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

    # Ajouter la réponse (les blocs de compactage sont automatiquement inclus)
    messages.append({"role": "assistant", "content": response.content})

    # Retourner le contenu textuel
    return next(block.text for block in response.content if block.type == "text")


# Exécuter une longue 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"))
# Continuer à appeler chat() aussi longtemps que la conversation le nécessite

Voici un exemple qui utilise pause_after_compaction pour préserver l'échange précédent et le message utilisateur actuel (trois messages au total) mot pour mot au lieu de les résumer :

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

    # Vérifier si la compaction a eu lieu et s'est mise en pause
    if response.stop_reason == "compaction":
        # Récupérer le bloc de compaction depuis la réponse
        compaction_block = response.content[0]

        # Préserver l'échange précédent + le message utilisateur actuel (3 messages)
        # en les incluant après le bloc de compaction
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Construire la nouvelle liste de messages : compaction + messages préservés
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Poursuivre la requête avec le contexte compacté + les messages préservés
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-8",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Mettre à jour notre liste de messages pour refléter la compaction
        messages.clear()
        messages.extend(messages_after_compaction)

    # Ajouter la réponse finale
    messages.append({"role": "assistant", "content": response.content})

    # Retourner le contenu textuel
    return next(block.text for block in response.content if block.type == "text")


# Exécuter une longue 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"))
# Continuer à appeler chat() aussi longtemps que la conversation le nécessite

Limitations actuelles

Même modèle pour le résumé : Le modèle spécifié dans votre requête est utilisé pour le résumé. Il n'existe aucune option pour utiliser un modèle différent (par exemple, moins cher) pour le résumé.
La compaction peut échouer lorsque des outils sont définis : Lorsque votre requête inclut tools, le modèle appelle parfois un outil pendant l'étape interne de résumé au lieu d'écrire un résumé. Lorsque cela se produit, la réponse contient un bloc compaction avec content: null. Pour éviter cela, définissez instructions avec un prompt qui indique explicitement au modèle de ne pas appeler d'outils, par exemple :
```
Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only.
```

Étapes suivantes

Édition de contexte

Gérez automatiquement le contexte de la conversation à mesure qu'il s'étend grâce à l'édition de contexte.

Fenêtres de contexte

Découvrez les tailles de fenêtres de contexte et les stratégies de gestion.

Cookbook de compaction de mémoire de session

Was this page helpful?

Modèles pris en charge

Fonctionnement de la compaction

Utilisation de base

Paramètres

Configuration du déclencheur

Instructions de résumé personnalisées

Mise en pause après la compaction

Application d'un budget total de tokens

Travailler avec les blocs de compaction

Renvoyer les blocs de compaction

Streaming

Mise en cache des prompts

Maximiser les correspondances de cache avec les invites système

Comprendre l'utilisation

Combinaison avec d'autres fonctionnalités

Outils serveur

Comptage de tokens

Exemples

Limitations actuelles

Étapes suivantes

Modèles pris en charge

Fonctionnement de la compaction

Utilisation de base

Paramètres

Configuration du déclencheur

Instructions de résumé personnalisées

Mise en pause après la compaction

Application d'un budget total de tokens

Travailler avec les blocs de compaction

Renvoyer les blocs de compaction

Streaming

Mise en cache des prompts

Maximiser les correspondances de cache avec les invites système

Comprendre l'utilisation

Combinaison avec d'autres fonctionnalités

Outils serveur

Comptage de tokens

Exemples

Limitations actuelles

Étapes suivantes

Modèles pris en charge

Fonctionnement de la compaction

Utilisation de base

Paramètres

Configuration du déclencheur

Instructions de résumé personnalisées

Mise en pause après la compaction

Application d'un budget total de tokens

Travailler avec les blocs de compaction

Renvoyer les blocs de compaction

Streaming

Mise en cache des prompts

Maximiser les correspondances de cache avec les invites système

Comprendre l'utilisation

Combinaison avec d'autres fonctionnalités

Outils serveur

Comptage de tokens

Exemples

Limitations actuelles

Étapes suivantes

Modèles pris en charge

Fonctionnement de la compaction

Utilisation de base

Paramètres

Configuration du déclencheur

Instructions de résumé personnalisées

Mise en pause après la compaction

Application d'un budget total de tokens

Travailler avec les blocs de compaction

Renvoyer les blocs de compaction

Streaming

Mise en cache des prompts

Maximiser les correspondances de cache avec les invites système

Comprendre l'utilisation

Combinaison avec d'autres fonctionnalités

Outils serveur

Comptage de tokens

Exemples

Limitations actuelles

Étapes suivantes