La modifica del contesto è attualmente in beta con supporto per la cancellazione dei risultati degli strumenti. Per abilitarla, usa l’header beta context-management-2025-06-27 nelle tue richieste API. Strategie aggiuntive di modifica del contesto verranno aggiunte nelle versioni future.Ti preghiamo di contattarci attraverso il nostro modulo di feedback per condividere il tuo feedback su questa funzionalità.

​
Come funziona

La strategia clear_tool_uses_20250919 cancella i risultati degli strumenti quando il contesto della conversazione supera la soglia configurata. Quando attivata, l’API cancella automaticamente i risultati degli strumenti più vecchi in ordine cronologico, sostituendoli con testo segnaposto per far sapere a Claude che il risultato dello strumento è stato rimosso. Per impostazione predefinita, vengono cancellati solo i risultati degli strumenti. Puoi opzionalmente cancellare sia i risultati degli strumenti che le chiamate agli strumenti (i parametri di utilizzo dello strumento) impostando clear_tool_inputs su true. La modifica del contesto invalida i prefissi di prompt memorizzati nella cache perché la cancellazione del contenuto modifica la struttura del prompt, rompendo il requisito di corrispondenza per i successi della cache. Per tenere conto di questo, raccomandiamo di cancellare abbastanza token per rendere l’invalidazione della cache utile. Usa il parametro clear_at_least per assicurarti che venga cancellato un numero minimo di token ogni volta. Quando usi la memorizzazione nella cache del prompt con la modifica del contesto, incorrerai in costi di scrittura della cache ogni volta che il contenuto viene cancellato, ma le richieste successive possono riutilizzare il prefisso appena memorizzato nella cache.

​
Modelli supportati

La modifica del contesto è disponibile su:
  • 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)

​
Utilizzo di base

Il modo più semplice per abilitare la modifica del contesto è specificare solo il tipo di strategia, poiché tutte le altre opzioni di configurazione useranno i loro valori predefiniti: 
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": "Cerca sviluppi recenti nell'\''AI"
            }
        ],
        "tools": [
            {
                "type": "web_search_20250305",
                "name": "web_search"
            }
        ],
        "context_management": {
            "edits": [
                {"type": "clear_tool_uses_20250919"}
            ]
        }
    }'

​
Configurazione avanzata

Puoi personalizzare il comportamento della modifica del contesto con parametri aggiuntivi: 
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": "Crea una semplice app calcolatrice da riga di comando usando 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"]
                }
            ]
        }
    }'

​
Opzioni di configurazione

Opzione di configurazionePredefinitoDescrizione
trigger100.000 token di inputDefinisce quando si attiva la strategia di modifica del contesto. Una volta che il prompt supera questa soglia, inizierà la cancellazione. Puoi specificare questo valore in input_tokens o tool_uses.
keep3 utilizzi di strumentiDefinisce quante coppie recenti di utilizzo/risultato dello strumento mantenere dopo che si verifica la cancellazione. L’API rimuove prima le interazioni con gli strumenti più vecchie, preservando quelle più recenti.
clear_at_leastNessunoAssicura che venga cancellato un numero minimo di token ogni volta che la strategia si attiva. Se l’API non può cancellare almeno la quantità specificata, la strategia non verrà applicata. Questo aiuta a determinare se la cancellazione del contesto vale la pena di rompere la cache del prompt.
exclude_toolsNessunoLista di nomi di strumenti i cui utilizzi e risultati non dovrebbero mai essere cancellati. Utile per preservare contesto importante.
clear_tool_inputsfalseControlla se i parametri della chiamata allo strumento vengono cancellati insieme ai risultati dello strumento. Per impostazione predefinita, vengono cancellati solo i risultati dello strumento mantenendo visibili le chiamate originali dello strumento di Claude.

​
Formato della risposta

Puoi vedere quali modifiche del contesto sono state applicate alla tua richiesta usando il campo di risposta context_management, insieme a statistiche utili sul contenuto e sui token di input cancellati.
Response
{
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [...],
    "usage": {...},
    "context_management": {
        "applied_edits": [
            {
                "type": "clear_tool_uses_20250919",
                "cleared_tool_uses": 8,
                "cleared_input_tokens": 50000
            }
        ]
    }
}
Per le risposte in streaming, le modifiche del contesto saranno incluse nell’evento finale message_delta:
Streaming Response
{
    "type": "message_delta",
    "delta": {
        "stop_reason": "end_turn",
        "stop_sequence": null
    },
    "usage": {
        "output_tokens": 1024
    },
    "context_management": {
        "applied_edits": [...]
    }
}

​
Conteggio dei token

L’endpoint /v1/messages/count_tokens supporta la gestione del contesto, permettendoti di vedere in anteprima quanti token userà il tuo prompt dopo che la modifica del contesto è stata applicata. 
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": "Continua la nostra conversazione..."
            }
        ],
        "tools": [...],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 5
                    }
                }
            ]
        }
    }'
Response
{
    "input_tokens": 25000,
    "context_management": {
        "original_input_tokens": 70000
    }
}
La risposta mostra sia il conteggio finale dei token dopo che la gestione del contesto è stata applicata (input_tokens) che il conteggio originale dei token prima che si verificasse qualsiasi cancellazione (original_input_tokens).