Édition du contexte

Vue d'ensemble

Le « context editing » (édition du contexte) vous permet d'effacer de manière sélective un contenu spécifique de l'historique de conversation à mesure qu'il s'accroît. Au-delà de l'optimisation des coûts et du respect des limites, il s'agit de sélectionner activement ce que Claude voit : le contexte est une ressource finie aux rendements décroissants, et un contenu non pertinent dégrade la concentration du modèle. L'édition du contexte vous donne un contrôle fin, à l'exécution, sur cette sélection. Pour les principes plus généraux qui sous-tendent la gestion du contexte, consultez Effective context engineering. Cette page couvre :

• Effacement des résultats d'outils - Idéal pour les flux de travail agentiques avec une utilisation d'outils intensive, où les anciens résultats d'outils ne sont plus nécessaires
• Effacement des blocs de réflexion - Pour gérer les blocs de réflexion lors de l'utilisation de la réflexion étendue, avec des options permettant de préserver la réflexion récente pour la continuité du contexte
• Compaction SDK côté client - Une alternative basée sur le SDK pour une gestion du contexte par résumé (la compaction côté serveur est généralement préférable)

Stratégies côté serveur

Effacement des résultats d'outils

La stratégie clear_tool_uses_20250919 efface les résultats d'outils lorsque le contexte de la conversation dépasse le seuil que vous avez configuré. Ceci est particulièrement utile pour les flux de travail agentiques avec une utilisation d'outils intensive. Les anciens résultats d'outils (comme le contenu de fichiers ou les résultats de recherche) ne sont plus nécessaires une fois que Claude les a traités.

Lorsqu'elle est activée, l'API efface automatiquement les résultats d'outils les plus anciens dans l'ordre chronologique. L'API remplace chaque résultat effacé par un texte de substitution indiquant à Claude qu'il a été supprimé. Par défaut, seuls les résultats d'outils sont effacés. Vous pouvez éventuellement effacer à la fois les résultats d'outils et les appels d'outils (les paramètres d'utilisation d'outils) en définissant clear_tool_inputs sur true.

Effacement des blocs de réflexion

La stratégie clear_thinking_20251015 gère les blocs thinking dans les conversations lorsque la « extended thinking » (réflexion étendue) est activée. Cette stratégie vous donne le contrôle sur la préservation de la réflexion : vous pouvez choisir de conserver davantage de blocs de réflexion pour maintenir la continuité du raisonnement, ou de les effacer plus agressivement pour économiser de l'espace de contexte.

Un tour de conversation de l'assistant peut inclure plusieurs blocs de contenu (par exemple, lors de l'utilisation d'outils) et plusieurs blocs de réflexion (par exemple, avec la réflexion entrelacée).

L'édition du contexte s'effectue côté serveur

L'édition du contexte est appliquée côté serveur avant que le prompt n'atteigne Claude. Votre application cliente conserve l'historique de conversation complet et non modifié. Vous n'avez pas besoin de synchroniser l'état de votre client avec la version éditée. Continuez à gérer localement votre historique de conversation complet comme vous le feriez normalement.

Sur Claude Fable 5.1 et Claude Opus 5.5, la gestion du contexte côté serveur n'invalide jamais les blocs de réflexion. Les modifications côté client apportées aux tours précédents peuvent invalider les blocs de réflexion de chaque tour ultérieur de l'assistant. Pour les nouveaux comptes créés à partir du 31 août 2026, une requête qui rejoue un bloc invalidé est rejetée, sauf si vous choisissez de le supprimer. Consultez Conserver le préfixe inchangé.

Édition du contexte et mise en cache des prompts

L'interaction de l'édition du contexte avec la mise en cache des prompts (« prompt caching ») varie selon la stratégie :

• Effacement des résultats d'outils : invalide les préfixes de prompt mis en cache lorsque du contenu est effacé. Pour en tenir compte, effacez suffisamment de tokens pour que l'invalidation du cache en vaille la peine. Utilisez le paramètre clear_at_least pour garantir qu'un nombre minimal de tokens est effacé à chaque fois. Vous supporterez des coûts d'écriture en cache chaque fois que du contenu est effacé, mais les requêtes suivantes pourront réutiliser le préfixe nouvellement mis en cache.

• Effacement des blocs de réflexion : lorsque les blocs de réflexion sont conservés dans le contexte (non effacés), le cache de prompts est préservé, ce qui permet des accès au cache et réduit les coûts en tokens d'entrée. Lorsque les blocs de réflexion sont effacés, le cache est invalidé à l'endroit où l'effacement se produit. Configurez le paramètre keep selon que vous souhaitez privilégier les performances du cache ou la disponibilité de la fenêtre de contexte.

Modèles pris en charge

L'édition du contexte est disponible sur tous les modèles Claude pris en charge.

Utilisation de l'effacement des résultats d'outils

La façon la plus simple d'activer l'effacement des résultats d'outils est de spécifier uniquement le type de stratégie. Toutes les autres options de configuration utilisent leurs valeurs par défaut :

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

Configuration avancée

Vous pouvez personnaliser le comportement de l'effacement des résultats d'outils avec des paramètres supplémentaires :

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # Déclencher l'effacement lorsque le seuil est dépassé
                "trigger": {"type": "input_tokens", "value": 30000},
                # Nombre d'utilisations d'outils à conserver après l'effacement
                "keep": {"type": "tool_uses", "value": 3},
                # Facultatif : effacer au moins ce nombre de tokens
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Exclure ces outils de l'effacement
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

Utilisation de l'effacement des blocs de réflexion

Activez l'effacement des blocs de réflexion pour gérer efficacement le contexte et la mise en cache des prompts lorsque la réflexion étendue est activée :

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)

Options de configuration pour l'effacement des blocs de réflexion

La stratégie clear_thinking_20251015 prend en charge la configuration suivante :

Exemples de configuration :

Conserver les blocs de réflexion des 3 derniers tours de l'assistant :

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

Conserver tous les blocs de réflexion (maximise les accès au cache) :

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)

Combinaison de stratégies

Vous pouvez utiliser conjointement l'effacement des blocs de réflexion et l'effacement des résultats d'outils :

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
                "keep": {"type": "tool_uses", "value": 5},
            },
        ]
    },
)

print(response)

Options de configuration pour l'effacement des résultats d'outils

Réponse de l'édition du contexte

Vous pouvez voir quelles éditions de contexte ont été appliquées à votre requête à l'aide du champ de réponse context_management, ainsi que des statistiques utiles sur le contenu et les tokens d'entrée effacés.

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // When using `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // When using `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

Pour les réponses en streaming, les éditions de contexte sont incluses dans l'événement final message_delta :

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

Comptage des tokens

Le point de terminaison de comptage des tokens prend en charge la gestion du contexte, ce qui vous permet de prévisualiser le nombre de tokens que votre prompt utilisera une fois l'édition du contexte appliquée.

response = client.beta.messages.count_tokens(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
)

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

La réponse indique à la fois le nombre final de tokens après application de la gestion du contexte (input_tokens) et le nombre de tokens d'origine avant tout effacement (original_input_tokens).

Utilisation avec l'outil de mémoire

L'édition du contexte peut être combinée avec l'outil de mémoire. Lorsque le contexte de votre conversation approche du seuil d'effacement configuré, Claude reçoit un avertissement automatique l'invitant à préserver les informations importantes. Cela permet à Claude d'enregistrer les résultats d'outils ou le contexte dans ses fichiers de mémoire avant qu'ils ne soient effacés de l'historique de conversation.

Cette combinaison vous permet de :

• Préserver le contexte important : Claude peut écrire les informations essentielles issues des résultats d'outils dans des fichiers de mémoire avant que ces résultats ne soient effacés
• Maintenir des flux de travail de longue durée : permettre des flux de travail agentiques qui dépasseraient autrement les limites de contexte en déchargeant les informations vers un stockage persistant
• Accéder aux informations à la demande : Claude peut rechercher des informations précédemment effacées dans les fichiers de mémoire lorsque c'est nécessaire, plutôt que de tout conserver dans la fenêtre de contexte active

Par exemple, dans un flux de travail d'édition de fichiers où Claude effectue de nombreuses opérations, Claude peut résumer les modifications terminées dans des fichiers de mémoire à mesure que le contexte s'accroît. Lorsque les résultats d'outils sont effacés, Claude conserve l'accès à ces informations via son système de mémoire et peut continuer à travailler efficacement.

Pour utiliser les deux fonctionnalités ensemble, activez-les dans votre requête API :

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

Pour la référence complète de l'outil de mémoire, y compris les commandes et les exemples, consultez Outil de mémoire.

Compaction côté client (SDK)

La compaction est une fonctionnalité du SDK qui gère automatiquement le contexte de la conversation en générant des résumés lorsque l'utilisation des tokens devient trop importante. Contrairement aux stratégies d'édition du contexte côté serveur qui effacent du contenu, la compaction demande à Claude de résumer l'historique de la conversation, puis remplace l'historique complet par ce résumé. Cela permet à Claude de continuer à travailler sur des tâches de longue durée qui dépasseraient autrement la fenêtre de contexte (« context window »).

Fonctionnement de la compaction

Lorsque la compaction est activée, le SDK surveille l'utilisation des tokens après chaque réponse du modèle :

1. Vérification du seuil : le SDK calcule le total des tokens comme input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens (voir Mise en cache des prompts pour les champs de tokens de cache).
2. Génération du résumé : lorsque le seuil est dépassé, un prompt de résumé est injecté en tant que tour utilisateur, et Claude génère un résumé structuré encadré par des balises <summary></summary>.
3. Remplacement du contexte : le SDK extrait le résumé et remplace l'intégralité de l'historique des messages par celui-ci.
4. Poursuite : la conversation reprend à partir du résumé, Claude reprenant là où il s'était arrêté.

Utilisation de la compaction

Ajoutez compaction_control à votre appel tool_runner pour activer le résumé automatique lorsque l'utilisation des tokens dépasse le seuil.

Ce qui se passe pendant la compaction

À mesure que la conversation s'accroît, l'historique des messages s'accumule :

Avant la compaction (approchant 100 000 tokens) :

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "After analyzing file2.txt..." }
  // ... 50 more exchanges like this ...
]

Lorsque les tokens dépassent le seuil, le SDK injecte une demande de résumé et Claude génère un résumé. L'intégralité de l'historique est alors remplacée :

Après la compaction (retour à environ 2 000 à 3 000 tokens) :

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claude continue à travailler à partir de ce résumé comme s'il s'agissait de l'historique de conversation d'origine.

Options de configuration

Choix d'un seuil de tokens

Le seuil détermine le moment où la compaction se produit. Un seuil plus bas signifie des compactions plus fréquentes avec des fenêtres de contexte plus petites. Un seuil plus élevé permet davantage de contexte mais risque d'atteindre les limites.

Utilisation d'un modèle différent pour les résumés

Vous pouvez utiliser un modèle plus rapide ou moins coûteux pour générer les résumés :

Prompts de résumé personnalisés

Vous pouvez fournir un prompt personnalisé pour des besoins propres à un domaine. Votre prompt doit demander à Claude d'encadrer son résumé par des balises <summary></summary>.

Prompt de résumé par défaut

Le prompt de résumé intégré demande à Claude de créer un résumé de continuation structuré comprenant :

1. Vue d'ensemble de la tâche : la demande principale de l'utilisateur, les critères de réussite et les contraintes.
2. État actuel : ce qui a été accompli, les fichiers modifiés et les artefacts produits.
3. Découvertes importantes : les contraintes techniques, les décisions prises, les erreurs résolues et les approches ayant échoué.
4. Prochaines étapes : les actions spécifiques nécessaires, les points de blocage et l'ordre de priorité.
5. Contexte à préserver : les préférences de l'utilisateur, les détails propres au domaine et les engagements pris.

Cette structure permet à Claude de reprendre le travail efficacement sans perdre de contexte important ni répéter des erreurs.

You have been working on the task described above but have not yet completed it. Write a continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary. Your summary should be structured, concise, and actionable. Include:

1. Task Overview
The user's core request and success criteria
Any clarifications or constraints they specified

2. Current State
What has been completed so far
Files created, modified, or analyzed (with paths if relevant)
Key outputs or artifacts produced

3. Important Discoveries
Technical constraints or requirements uncovered
Decisions made and their rationale
Errors encountered and how they were resolved
What approaches were tried that didn't work (and why)

4. Next Steps
Specific actions needed to complete the task
Any blockers or open questions to resolve
Priority order if multiple steps remain

5. Context to Preserve
User preferences or style requirements
Domain-specific details that aren't obvious
Any promises made to the user

Be concise but complete—err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.

Wrap your summary in <summary></summary> tags.

Limitations

Outils côté serveur

Lors de l'utilisation d'outils côté serveur, le SDK peut calculer incorrectement l'utilisation des tokens, ce qui déclenche la compaction au mauvais moment.

Par exemple, après une opération de recherche web, la réponse de l'API peut indiquer :

{
  "usage": {
    "input_tokens": 63000,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

Le SDK calcule l'utilisation totale comme 63 000 + 0 + 270 000 + 1 400 = 334 400 tokens. Cependant, la valeur cache_read_input_tokens inclut les lectures cumulées de plusieurs appels API internes effectués par l'outil côté serveur, et non le contexte réel de votre conversation. La longueur réelle de votre contexte peut n'être que les 63 000 input_tokens, mais le SDK voit 334 000 et déclenche la compaction prématurément.

Solutions de contournement :

• Utilisez le point de terminaison de comptage des tokens pour obtenir une longueur de contexte précise
• Évitez la compaction lorsque vous utilisez intensivement des outils côté serveur

Cas limites de l'utilisation d'outils

Lorsque le SDK déclenche la compaction alors qu'une réponse d'utilisation d'outil est en attente, il supprime le bloc d'utilisation d'outil de l'historique des messages avant de générer le résumé. Claude réémettra l'appel d'outil après la reprise à partir du résumé s'il est toujours nécessaire.

Surveillance de la compaction

Comprendre quand la compaction se déclenche vous aide à ajuster les seuils et à vérifier le comportement attendu.

Quand utiliser la compaction

Bons cas d'usage :

• Tâches d'agent de longue durée qui traitent de nombreux fichiers ou sources de données
• Flux de travail de recherche qui accumulent de grandes quantités d'informations
• Tâches en plusieurs étapes avec une progression claire et mesurable
• Tâches qui produisent des artefacts (fichiers, rapports) qui persistent en dehors de la conversation

Cas d'usage moins adaptés :

• Tâches nécessitant un rappel précis des détails du début de la conversation
• Flux de travail utilisant intensivement des outils côté serveur
• Tâches qui doivent maintenir un état exact sur de nombreuses variables

Prochaines étapes