Édition du contexte



Vue d'ensemble

L'édition du contexte vous permet d'effacer sélectivement du 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 avec des rendements décroissants, et le contenu non pertinent dégrade la concentration du modèle. L'édition du contexte vous offre un contrôle fin à l'exécution sur cette sélection. Pour les principes plus généraux de la gestion du contexte, consultez Effective context engineering. Cette page couvre :

• Effacement des résultats d'outils - Idéal pour les workflows 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 pour préserver la réflexion récente afin de maintenir la continuité du contexte
• Compaction SDK côté client - Une alternative basée sur le SDK pour la 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 conversation dépasse le seuil que vous avez configuré. Ceci est particulièrement utile pour les workflows 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 afin que Claude sache 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 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 votre historique de conversation complet localement comme vous le feriez normalement.



Édition du contexte et mise en cache des prompts

L'interaction de l'édition du contexte avec la mise en cache des prompts 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 minimum de tokens est effacé à chaque fois. Vous encourrez des coûts d'écriture de cache chaque fois que du contenu est effacé, mais les requêtes suivantes peuvent 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 prompt est préservé, ce qui permet des correspondances de cache et réduit les coûts de tokens d'entrée. Lorsque les blocs de réflexion sont effacés, le cache est invalidé au point 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 :



Configuration avancée

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



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 :



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 configurations :

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

Conserver tous les blocs de réflexion (maximise les correspondances de cache) :



Combinaison de stratégies

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



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 en utilisant le 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 de tokens

Le point de terminaison de comptage de tokens prend en charge la gestion du contexte, ce qui vous permet de prévisualiser le nombre de tokens que votre prompt utilisera après l'application de l'édition du contexte.

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

La réponse affiche à la fois le nombre final de tokens après l'application de la gestion du contexte (input_tokens) et le nombre de tokens original 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 pour 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 des résultats d'outils dans des fichiers de mémoire avant que ces résultats ne soient effacés
• Maintenir des workflows de longue durée : Permettre des workflows 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 consulter les informations précédemment effacées à partir des fichiers de mémoire lorsque nécessaire, plutôt que de tout conserver dans la fenêtre de contexte active

Par exemple, dans un workflow 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 :

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 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 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.



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.
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. Continuation : 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 produit pendant la compaction

À mesure que la conversation s'allonge, l'historique des messages s'accumule :

Avant la compaction (approchant 100k 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'historique entier est alors remplacé :

Après la compaction (retour à ~2–3k 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 original.



Options de configuration



Choisir un seuil de tokens

Le seuil détermine quand 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 plus de contexte mais risque d'atteindre les limites.



Utiliser 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 spécifiques à un domaine. Votre prompt doit demander à Claude d'encadrer son résumé avec 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. Aperçu 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 : Contraintes techniques, décisions prises, erreurs résolues et approches ayant échoué.
4. Prochaines étapes : Actions spécifiques nécessaires, blocages et ordre de priorité.
5. Contexte à préserver : Préférences de l'utilisateur, détails spécifiques au domaine et engagements pris.

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



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 pourrait afficher :

{
  "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 accumulées de plusieurs appels API internes effectués par l'outil côté serveur, et non la longueur réelle du contexte de votre conversation. La longueur réelle de votre contexte pourrait n'être que les 63 000 input_tokens, mais le SDK voit 334k et déclenche la compaction prématurément.

Solutions de contournement :

• Utilisez le point de terminaison de comptage de tokens pour obtenir la longueur de contexte exacte
• Évitez la compaction lors d'une utilisation intensive d'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 avoir repris à partir du résumé si cela 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
• Workflows 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
• Workflows utilisant intensivement des outils côté serveur
• Tâches qui doivent maintenir un état exact sur de nombreuses variables



Prochaines étapes