Édition du contexte

Aperçu

L'édition du contexte vous permet de gérer automatiquement le contexte de la conversation à mesure qu'il se développe, vous aidant à optimiser les coûts et à rester dans les limites de la fenêtre de contexte. L'API fournit différentes stratégies pour gérer le contexte :

• Effacement des résultats d'outils (clear_tool_uses_20250919) : Efface automatiquement les paires utilisation d'outil/résultat lorsque le contexte de la conversation dépasse votre seuil configuré
• Effacement des blocs de réflexion (clear_thinking_20251015) : Gère les blocs de réflexion en effaçant les blocs de réflexion plus anciens des tours précédents

Chaque stratégie peut être configurée indépendamment et appliquée ensemble pour optimiser votre cas d'usage spécifique.

Stratégies d'édition du contexte

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 votre seuil configuré. Lorsqu'elle est activée, l'API efface automatiquement les résultats d'outils les plus anciens dans l'ordre chronologique, en les remplaçant par un texte d'espace réservé pour informer Claude que le résultat d'outil 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'outil) 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 efface automatiquement les blocs de réflexion plus anciens des tours précédents.

Modèles supportés

L'édition du contexte est disponible sur :

• 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, car toutes les autres options de configuration utiliseront 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-sonnet-4-5",
        "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"}
            ]
        }
    }'

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

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-5",
  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" }
    ]
  },
  betas: ["context-management-2025-06-27"]
});

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-sonnet-4-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
            }
        ],
        "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-sonnet-4-5-20250929",
        "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 supporte la configuration suivante :

Exemples de configurations :

// 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-sonnet-4-5-20250929",
    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 requête 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 supporte la gestion du contexte, vous permettant de prévisualiser combien de jetons 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-sonnet-4-5",
        "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 la 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 de longue durée : Activez les flux de travail d'agent 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 requête API :

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