Compaction

ConstruireGestion du contexte

Compaction

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

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

La compaction côté serveur est la stratégie recommandée pour gérer le contexte dans les conversations longues et les flux de travail d'agents. Elle gère automatiquement la gestion du contexte avec un travail d'intégration minimal.

La compaction étend la longueur effective du contexte pour les conversations et tâches longues en résumant automatiquement le contexte ancien lorsqu'on approche de la limite de la fenêtre de contexte. Il ne s'agit pas seulement de rester sous un plafond de jetons. À mesure que les conversations s'allongent, les modèles ont du mal à maintenir leur attention sur l'historique complet. La compaction garde le contexte actif concentré et performant en remplaçant le contenu obsolète par des résumés concis.

Pour une analyse plus approfondie de la raison pour laquelle les longs contextes se dégradent et comment la compaction aide, consultez Effective context engineering.

C'est idéal pour :

Les conversations basées sur le chat, multi-tours où vous voulez que les utilisateurs utilisent un seul chat pendant une longue période
Les invites orientées vers les tâches qui nécessitent beaucoup de travail de suivi (souvent l'utilisation d'outils) qui peuvent dépasser la fenêtre de contexte

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

Modèles supportés

La compaction est supportée sur les modèles suivants :

Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-4-6)

Comment fonctionne la compaction

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

Détecte quand les jetons d'entrée dépassent 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é.
Continue la réponse avec le contexte compacté.

Pour les demandes ultérieures, ajoutez la réponse à vos messages. L'API supprime automatiquement tous les blocs de messages antérieurs au bloc compaction, en continuant la conversation à partir du résumé.

Diagramme de flux montrant le processus de compaction : lorsque les jetons d'entrée dépassent le seuil de déclenchement, Claude génère un résumé dans un bloc de compaction et continue 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 demande Messages API.

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

# Append the response (including any compaction block) to continue the conversation
messages.append({"role": "assistant", "content": response.content})

Paramètres

Paramètre	Type	Par défaut	Description
`type`	string	Requis	Doit être `"compact_20260112"`
`trigger`	object	150 000 jetons	Quand déclencher la compaction. Doit être au moins 50 000 jetons.
`pause_after_compaction`	boolean	`false`	S'il faut faire une pause après la génération du résumé de compaction
`instructions`	string	`null`	Invite de résumé personnalisée. Remplace complètement l'invite par défaut lorsqu'elle est fournie.

Configuration du déclenchement

Configurez quand la compaction se déclenche en utilisant le 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-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

Instructions de résumé personnalisées

Par défaut, la compaction utilise l'invite de résumé suivante :

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 pour remplacer complètement cette invite. Les instructions personnalisées ne complètent pas la valeur par défaut ; elles la 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-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

Pause après compaction

Utilisez pause_after_compaction pour mettre en pause l'API 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 des messages récents ou des messages spécifiques aux instructions) avant que l'API ne continue avec la réponse.

Lorsqu'elle est activée, l'API retourne un message avec la raison d'arrêt compaction après la génération du 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-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Check if compaction triggered a pause
if response.stop_reason == "compaction":
    # Response contains only the compaction block
    messages.append({"role": "assistant", "content": response.content})

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

Application d'un budget total de jetons

Lorsqu'un modèle travaille sur des tâches longues avec de nombreuses itérations d'utilisation d'outils, la consommation totale de jetons peut augmenter considérablement. Vous pouvez combiner pause_after_compaction avec un compteur de compaction pour estimer l'utilisation cumulative et terminer gracieusement la tâche une fois qu'un budget est atteint :

Python

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

    # Estimate total tokens consumed; prompt wrap-up if over budget
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

Utilisation des blocs de compaction

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

Une conversation longue peut entraîner plusieurs compactions. Le dernier bloc de compaction reflète l'état final de l'invite, remplaçant le contenu antérieur 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..."
    }
  ]
}

Transmission des blocs de compaction

Vous devez transmettre le bloc compaction à l'API lors des demandes suivantes pour continuer la conversation avec l'invite raccourcie. 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-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})

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

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

Lorsque l'API reçoit un bloc compaction, tous les blocs de contenu avant lui 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 inclure uniquement le bloc de compaction et au-delà

Streaming

Lors du streaming de réponses avec la compaction activée, vous recevrez un événement content_block_start lorsque la compaction commence. Le bloc de compaction se diffuse différemment des blocs de texte. Vous recevrez un événement content_block_start, suivi d'un seul content_block_delta avec le contenu du résumé complet (pas de 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-7",
    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)} chars")
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

    # Get the final accumulated message
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Mise en cache des invites

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

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

Maximiser les accès au 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, ce qui nécessiterait qu'elle soit remise en cache avec le résumé de compaction.

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

Le cache d'invite système reste valide et est lu à partir du cache
Seul le résumé de compaction doit être écrit comme une 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-7",
    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"}]},
)

Cette approche est particulièrement bénéfique pour les invites système longues, car elles restent mises en cache même à 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 retourne 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 affiche l'utilisation pour chaque itération d'échantillonnage. Lorsque la compaction se produit, vous verrez une itération compaction suivie de l'itération message principale. Les input_tokens et output_tokens au niveau supérieur correspondent exactement à l'itération message dans cet exemple car il n'y a qu'une seule itération sans compaction. Les comptages de jetons de l'itération finale reflètent la taille de contexte effective après compaction.

Les input_tokens et output_tokens au niveau supérieur n'incluent pas l'utilisation de l'itération de compaction. Ils reflètent la somme de toutes les itérations sans compaction. Pour calculer le total des jetons consommés et facturés pour une demande, additionnez tous les éléments du tableau usage.iterations.

Si vous aviez précédemment compté 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 les données de usage.iterations lorsque la compaction est activée. Le tableau iterations n'est rempli que lorsqu'une nouvelle compaction est déclenchée lors de la demande. 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 au 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 seule demande en fonction de votre seuil de déclenchement et de la quantité de sortie générée.

Comptage des jetons

Le point de terminaison de comptage des jetons (/v1/messages/count_tokens) applique les blocs compaction existants dans votre invite mais ne déclenche pas de nouvelles compactions. Utilisez-le pour vérifier votre comptage de jetons effectif 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-7",
    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 longue 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-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Append response (compaction blocks are automatically included)
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long 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"))
# ... continue as long as needed

Voici un exemple qui utilise pause_after_compaction pour préserver l'échange antérieur et le message utilisateur actuel (trois messages au total) textuellement 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-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Check if compaction occurred and paused
    if response.stop_reason == "compaction":
        # Get the compaction block from the response
        compaction_block = response.content[0]

        # Preserve the prior exchange + current user message (3 messages)
        # by including them after the compaction block
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Build new message list: compaction + preserved messages
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Continue the request with the compacted context + preserved messages
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-7",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Update our message list to reflect the compaction
        messages.clear()
        messages.extend(messages_after_compaction)

    # Append the final response
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long 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"))
# ... continue as long as needed

Limitations actuelles

Même modèle pour la résumé : Le modèle spécifié dans votre requête est utilisé pour la résumé. Il n'y a pas d'option pour utiliser un modèle différent (par exemple, moins cher) pour la résumé.

Étapes suivantes

Cookbook de compaction de mémoire de session

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

Fenêtres de contexte

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

Édition de contexte

Explorez d'autres stratégies pour gérer le contexte de conversation comme l'effacement des résultats d'outils et l'effacement des blocs de réflexion.

Was this page helpful?

ConstruireGestion du contexte

Compaction

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

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Pour une analyse plus approfondie de la raison pour laquelle les longs contextes se dégradent et comment la compaction aide, consultez Effective context engineering.

C'est idéal pour :

Les conversations basées sur le chat, multi-tours où vous voulez que les utilisateurs utilisent un seul chat pendant une longue période
Les invites orientées vers les tâches qui nécessitent beaucoup de travail de suivi (souvent l'utilisation d'outils) qui peuvent dépasser la fenêtre de contexte

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

Modèles supportés

La compaction est supportée sur les modèles suivants :

Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-4-6)

Comment fonctionne la compaction

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

Détecte quand les jetons d'entrée dépassent 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é.
Continue 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 demande Messages API.

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

# Append the response (including any compaction block) to continue the conversation
messages.append({"role": "assistant", "content": response.content})

Paramètres

Paramètre	Type	Par défaut	Description
`type`	string	Requis	Doit être `"compact_20260112"`
`trigger`	object	150 000 jetons	Quand déclencher la compaction. Doit être au moins 50 000 jetons.
`pause_after_compaction`	boolean	`false`	S'il faut faire une pause après la génération du résumé de compaction
`instructions`	string	`null`	Invite de résumé personnalisée. Remplace complètement l'invite par défaut lorsqu'elle est fournie.

Configuration du déclenchement

Configurez quand la compaction se déclenche en utilisant le 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-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

Instructions de résumé personnalisées

Par défaut, la compaction utilise l'invite de résumé suivante :

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.

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

Pause après compaction

Lorsqu'elle est activée, l'API retourne un message avec la raison d'arrêt compaction après la génération du 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-7",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Check if compaction triggered a pause
if response.stop_reason == "compaction":
    # Response contains only the compaction block
    messages.append({"role": "assistant", "content": response.content})

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

Application d'un budget total de jetons

Python

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

    # Estimate total tokens consumed; prompt wrap-up if over budget
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

Utilisation des blocs de compaction

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

Une conversation longue peut entraîner plusieurs compactions. Le dernier bloc de compaction reflète l'état final de l'invite, remplaçant le contenu antérieur 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..."
    }
  ]
}

Transmission des 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-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})

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

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

Lorsque l'API reçoit un bloc compaction, tous les blocs de contenu avant lui 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 inclure uniquement le bloc de compaction et au-delà

Streaming

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

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

    # Get the final accumulated message
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Mise en cache des invites

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

Maximiser les accès au cache avec les invites système

Le cache d'invite système reste valide et est lu à partir du cache
Seul le résumé de compaction doit être écrit comme une 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-7",
    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"}]},
)

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 des jetons

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

    # Append response (compaction blocks are automatically included)
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long 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"))
# ... continue as long as needed

Voici un exemple qui utilise pause_after_compaction pour préserver l'échange antérieur et le message utilisateur actuel (trois messages au total) textuellement 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-7",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Check if compaction occurred and paused
    if response.stop_reason == "compaction":
        # Get the compaction block from the response
        compaction_block = response.content[0]

        # Preserve the prior exchange + current user message (3 messages)
        # by including them after the compaction block
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Build new message list: compaction + preserved messages
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Continue the request with the compacted context + preserved messages
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-7",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Update our message list to reflect the compaction
        messages.clear()
        messages.extend(messages_after_compaction)

    # Append the final response
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long 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"))
# ... continue as long as needed

Limitations actuelles

Même modèle pour la résumé : Le modèle spécifié dans votre requête est utilisé pour la résumé. Il n'y a pas d'option pour utiliser un modèle différent (par exemple, moins cher) pour la résumé.

Étapes suivantes

Cookbook de compaction de mémoire de session

Fenêtres de contexte

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

Édition de contexte

Explorez d'autres stratégies pour gérer le contexte de conversation comme l'effacement des résultats d'outils et l'effacement des blocs de réflexion.

Was this page helpful?