Édition de contexte

Aperçu

L'édition de contexte vous permet d'effacer sélectivement du contenu spécifique de l'historique de conversation à mesure qu'il augmente. Au-delà de l'optimisation des coûts et du respect des limites, il s'agit de curer 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 de contexte vous donne un contrôle d'exécution granulaire sur cette curation. Pour les principes plus larges derrière la gestion du contexte, consultez Ingénierie de contexte efficace. Cette page couvre :

• Effacement des résultats d'outils - Idéal pour les flux de travail d'agents avec une utilisation intensive d'outils 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 pour la continuité du contexte
• Compaction SDK côté client - Une alternative basée sur SDK pour la gestion du contexte basée sur des résumés (la compaction côté serveur est généralement préférée)

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 votre seuil configuré. Ceci est particulièrement utile pour les flux de travail d'agents avec une utilisation intensive d'outils. Les anciens résultats d'outils (comme les contenus 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 d'espace réservé pour 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 plus de blocs de réflexion pour maintenir la continuité du raisonnement, ou les effacer plus agressivement pour économiser l'espace de contexte.

Un tour de conversation d'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 de contexte se fait côté serveur

L'édition de contexte est appliquée côté serveur avant que l'invite n'atteigne Claude. Votre application client maintient 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 de contexte et mise en cache des invites

L'interaction de l'édition de contexte avec la mise en cache des invites varie selon la stratégie :

• Effacement des résultats d'outils : Invalide les préfixes d'invite mis en cache lorsque du contenu est effacé. Pour tenir compte de cela, effacez suffisamment de jetons pour que l'invalidation du cache en vaille la peine. Utilisez le paramètre clear_at_least pour assurer qu'un nombre minimum de jetons est effacé à chaque fois. Vous engagerez des coûts d'écriture de cache chaque fois que du contenu est effacé, mais les requêtes ultérieures 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 d'invite est préservé, permettant les accès au cache et réduisant les coûts des jetons 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 prioriser les performances du cache ou la disponibilité de la fenêtre de contexte.

Modèles supportés

L'édition de contexte est disponible sur tous les modèles Claude supportés.

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

Le moyen le 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-4-7",
    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 d'effacement des résultats d'outils avec des paramètres supplémentaires :

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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",
                # Trigger clearing when threshold is exceeded
                "trigger": {"type": "input_tokens", "value": 30000},
                # Number of tool uses to keep after clearing
                "keep": {"type": "tool_uses", "value": 3},
                # Optional: Clear at least this many tokens
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Exclude these tools from being cleared
                "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 invites lorsque la réflexion étendue est activée :

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
    thinking={"type": "enabled", "budget_tokens": 10000},
    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 d'assistant :

{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

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

{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Combinaison de stratégies

Vous pouvez utiliser à la fois l'effacement des blocs de réflexion et l'effacement des résultats d'outils ensemble :

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[...],
    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},
            },
        ]
    },
)

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

Réponse d'édition de contexte

Vous pouvez voir quelles éditions de contexte ont été appliquées à votre demande en utilisant le champ de réponse context_management, ainsi que des statistiques utiles sur le contenu et les jetons d'entrée effacés.

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // Lors de l'utilisation de `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // Lors de l'utilisation de `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 seront 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 jetons

Le point de terminaison comptage des jetons prend en charge la gestion du contexte, vous permettant de prévisualiser le nombre de jetons que votre invite utilisera après l'application de l'édition de contexte.

response = client.beta.messages.count_tokens(
    model="claude-opus-4-7",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    tools=[...],  # Your tool definitions
    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 affiche à la fois le nombre final de jetons après l'application de la gestion du contexte (input_tokens) et le nombre original de jetons avant tout effacement (original_input_tokens).

Utilisation avec l'outil Memory

La modification du contexte peut être combinée avec l'outil memory. Lorsque votre contexte de 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 des outils ou le contexte dans ses fichiers memory 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 des outils dans les fichiers memory avant que ces résultats ne soient effacés
• Maintenir les workflows de longue durée : Activer les 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 rechercher les informations précédemment effacées dans les fichiers memory si nécessaire, plutôt que de garder tout 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 les fichiers memory à mesure que le contexte augmente. Lorsque les résultats des outils sont effacés, Claude conserve l'accès à ces informations via son système memory 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-4-7",
    max_tokens=4096,
    messages=[...],
    tools=[
        {"type": "memory_20250818", "name": "memory"},
        # Your other tools
    ],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

Pour la référence complète de l'outil memory incluant les commandes et les exemples, consultez Memory tool.

Compaction côté client (SDK)

La compaction est une fonctionnalité 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 de modification du contexte côté serveur qui effacent le 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.

Comment fonctionne 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é, une invite de résumé est injectée comme un tour utilisateur, et Claude génère un résumé structuré enveloppé dans 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 la résumé automatique lorsque l'utilisation des tokens dépasse le seuil.

Ce qui se passe pendant la compaction

À mesure que la conversation augmente, 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'intégralité de l'historique est ensuite remplacée :

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 inférieur 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.

# More frequent compaction for memory-constrained scenarios
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# Less frequent compaction when you need more context
compaction_control = {"enabled": True, "context_token_threshold": 150000}

Utiliser un modèle différent pour les résumés

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

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5",
}

Invites de résumé personnalisées

Vous pouvez fournir une invite personnalisée pour les besoins spécifiques au domaine. Votre invite doit demander à Claude d'envelopper son résumé dans des balises <summary></summary>.

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags.""",
}

Invite de résumé par défaut

L'invite de résumé intégrée demande à Claude de créer un résumé de continuation structuré incluant :

1. Aperçu de la tâche : La demande principale de l'utilisateur, les critères de succès et les contraintes.
2. État actuel : Ce qui a été complété, 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 qui n'ont pas fonctionné.
4. Prochaines étapes : Les actions spécifiques nécessaires, les blocages et l'ordre de priorité.
5. Contexte à préserver : Les préférences de l'utilisateur, les détails spécifiques au domaine et les engagements pris.

Cette structure permet à Claude de reprendre le travail efficacement sans perdre le contexte important ou répéter les 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 entraîne le déclenchement de 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_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

Le SDK calcule l'utilisation totale comme 63 000 + 270 000 = 333 000 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 votre contexte de conversation réel. Votre longueur de contexte réelle pourrait être seulement les 63 000 input_tokens, mais le SDK en voit 333k et déclenche la compaction prématurément.

Solutions de contournement :

• Utilisez le point de terminaison de comptage des tokens pour obtenir la longueur de contexte exacte
• Évitez la compaction lors de l'utilisation extensive d'outils côté serveur

Cas limites d'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éédiera l'appel d'outil après la reprise à partir du résumé si 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 :

• Les tâches d'agent de longue durée qui traitent de nombreux fichiers ou sources de données
• Les workflows de recherche qui accumulent de grandes quantités d'informations
• Les tâches multi-étapes avec des progrès clairs et mesurables
• Les tâches qui produisent des artefacts (fichiers, rapports) qui persistent en dehors de la conversation

Cas d'usage moins idéaux :

• Les tâches nécessitant un rappel précis des détails de la conversation précoce
• Les workflows utilisant des outils côté serveur de manière extensive
• Les tâches qui doivent maintenir un état exact sur de nombreuses variables