Édition du contexte

Aperçu

L'édition du contexte vous permet d'effacer sélectivement du contenu spécifique de l'historique de conversation à mesure qu'il se développe. Cela vous aide à optimiser les coûts et à rester dans les limites de la fenêtre de contexte. 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 côté client du SDK - Une alternative basée sur le SDK pour la gestion du contexte basée sur les 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 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. Chaque résultat effacé est remplacé 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 du contexte se fait côté serveur

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

L'interaction de l'édition du 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 encourrez des coûts d'écriture de cache à chaque fois que du contenu est effacé, mais les demandes suivantes peuvent réutiliser le nouveau préfixe 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 pris en charge

L'édition du contexte est disponible sur :

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

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 :

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Search for recent developments in AI"
            }
        ],
        "tools": [
            {
                "type": "web_search_20250305",
                "name": "web_search"
            }
        ],
        "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 :

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "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
            }
        ],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 3
                    },
                    "clear_at_least": {
                        "type": "input_tokens",
                        "value": 5000
                    },
                    "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 :

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "messages": [...],
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10000
        },
        "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 :

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "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=1024,
    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 du 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": [
            // 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 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 du contexte.

curl https://api.anthropic.com/v1/messages/count_tokens \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "messages": [
            {
                "role": "user",
                "content": "Continue our conversation..."
            }
        ],
        "tools": [...],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 5
                    }
                }
            ]
        }
    }'

{
    "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 Mémoire

L'édition du contexte peut être combinée avec l'outil 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 de sauvegarder les résultats d'outils ou le contexte dans ses fichiers 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 les fichiers mémoire avant que ces résultats ne soient effacés
• Maintenir les flux de travail longue durée : Activer les flux de travail d'agents 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 à partir des fichiers mémoire si 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 les fichiers mémoire à mesure que le contexte se développe. Lorsque les résultats d'outils sont effacés, Claude conserve l'accès à ces informations via son système mémoire et peut continuer à travailler efficacement.

Pour utiliser les deux fonctionnalités ensemble, activez-les dans votre demande d'API :

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}
        ]
    }
)

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 jetons devient trop importante. Contrairement aux stratégies d'édition 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 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 jetons après chaque réponse du modèle :

1. Vérification du seuil : Le SDK calcule le total des jetons 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'historique des messages entier 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 :

import anthropic

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=[...],
    messages=[
        {
            "role": "user",
            "content": "Analyze all the files in this directory and write a summary report."
        }
    ],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000
    }
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

final = runner.until_done()

Ce qui se passe pendant la compaction

À mesure que la conversation se développe, l'historique des messages s'accumule :

Avant la compaction (approchant 100k jetons) :

[
  { "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 jetons dépassent le seuil, le SDK injecte une demande de résumé et Claude génère un résumé. L'historique entier est ensuite remplacé :

Après la compaction (retour à ~2-3k jetons) :

[
  {
    "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

Choix d'un seuil de jetons

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
}

Utilisation d'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 échouées.
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 de contexte important ni 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 jetons, ce qui provoque 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 jetons. 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 voit 333k et déclenche la compaction prématurément.

Solutions de contournement :

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

Cas limites d'utilisation d'outils

Lorsque la compaction est déclenchée alors qu'une réponse d'utilisation d'outil est en attente, le SDK 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é si cela est toujours nécessaire.

Surveillance de la compaction

Activez la journalisation pour suivre quand la compaction se produit :

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# Logs will show:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

Quand utiliser la compaction

Bons cas d'utilisation :

• Les tâches d'agent longues qui traitent de nombreux fichiers ou sources de données
• Les flux de travail de recherche qui accumulent de grandes quantités d'informations
• Les tâches multi-étapes avec une progression claire et mesurable
• Les tâches qui produisent des artefacts (fichiers, rapports) qui persistent en dehors de la conversation

Cas d'utilisation moins idéaux :

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