Modifica del contesto
La modifica del contesto è attualmente in beta con supporto per la cancellazione dei risultati degli strumenti e la cancellazione dei blocchi di pensiero. Per abilitarla, utilizza l'intestazione beta context-management-2025-06-27 nelle tue richieste API.
Ti invitiamo a contattarci tramite il nostro modulo di feedback per condividere il tuo feedback su questa funzione.
Panoramica
La modifica del contesto ti consente di gestire automaticamente il contesto della conversazione man mano che cresce, aiutandoti a ottimizzare i costi e rimanere entro i limiti della finestra di contesto. L'API fornisce diverse strategie per gestire il contesto:
- Cancellazione dei risultati degli strumenti (
clear_tool_uses_20250919): Cancella automaticamente le coppie di utilizzo/risultato degli strumenti quando il contesto della conversazione supera la soglia configurata - Cancellazione dei blocchi di pensiero (
clear_thinking_20251015): Gestisce i blocchi di pensiero cancellando i blocchi di pensiero più vecchi dai turni precedenti
Ogni strategia può essere configurata indipendentemente e applicata insieme per ottimizzare il tuo caso d'uso specifico.
Strategie di modifica del contesto
Cancellazione dei risultati degli strumenti
La strategia clear_tool_uses_20250919 cancella i risultati degli strumenti quando il contesto della conversazione cresce oltre 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 facoltativamente cancellare sia i risultati degli strumenti che le chiamate agli strumenti (i parametri di utilizzo dello strumento) impostando clear_tool_inputs su true.
Cancellazione dei blocchi di pensiero
La strategia clear_thinking_20251015 gestisce i blocchi thinking nelle conversazioni quando il pensiero esteso è abilitato. Questa strategia cancella automaticamente i blocchi di pensiero più vecchi dai turni precedenti.
Comportamento predefinito: Quando il pensiero esteso è abilitato senza configurare la strategia clear_thinking_20251015, l'API mantiene automaticamente solo i blocchi di pensiero dall'ultimo turno dell'assistente (equivalente a keep: {type: "thinking_turns", value: 1}).
Per massimizzare i cache hit, preserva tutti i blocchi di pensiero impostando keep: "all".
Un turno di conversazione dell'assistente può includere più blocchi di contenuto (ad es. quando si utilizzano strumenti) e più blocchi di pensiero (ad es. con pensiero intercalato).
La modifica del contesto avviene lato server
La modifica del contesto viene applicata lato server prima che il prompt raggiunga Claude. La tua applicazione client mantiene la cronologia completa e non modificata della conversazione: non è necessario sincronizzare lo stato del client con la versione modificata. Continua a gestire la tua cronologia di conversazione completa localmente come faresti normalmente.
Modifica del contesto e caching del prompt
L'interazione della modifica del contesto con il caching del prompt varia a seconda della strategia:
-
Cancellazione dei risultati degli strumenti: Invalida i prefissi del prompt memorizzati nella cache quando il contenuto viene cancellato. Per tenerne conto, consigliamo di cancellare abbastanza token per rendere l'invalidazione della cache utile. Utilizza il parametro
clear_at_leastper garantire che un numero minimo di token venga cancellato ogni volta. 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. -
Cancellazione dei blocchi di pensiero: Quando i blocchi di pensiero vengono mantenuti nel contesto (non cancellati), la cache del prompt viene preservata, abilitando i cache hit e riducendo i costi dei token di input. Quando i blocchi di pensiero vengono cancellati, la cache viene invalidata nel punto in cui si verifica la cancellazione. Configura il parametro
keepin base al fatto che tu voglia dare priorità alle prestazioni della cache o alla disponibilità della finestra di contesto.
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) - Claude Haiku 4.5 (
claude-haiku-4-5-20251001)
Utilizzo della cancellazione dei risultati degli strumenti
Il modo più semplice per abilitare la cancellazione dei risultati degli strumenti è specificare solo il tipo di strategia, poiché tutte le altre opzioni di configurazione utilizzeranno 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": "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"]
});Configurazione avanzata
Puoi personalizzare il comportamento della cancellazione dei risultati degli strumenti 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": "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"]
}
]
}
}'Utilizzo della cancellazione dei blocchi di pensiero
Abilita la cancellazione dei blocchi di pensiero per gestire efficacemente il contesto e il caching del prompt quando il pensiero esteso è abilitato:
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
}
}
]
}
}'Opzioni di configurazione per la cancellazione dei blocchi di pensiero
La strategia clear_thinking_20251015 supporta la seguente configurazione:
| Opzione di configurazione | Predefinito | Descrizione |
|---|---|---|
keep | {type: "thinking_turns", value: 1} | Definisce quanti turni recenti dell'assistente con blocchi di pensiero preservare. Utilizza {type: "thinking_turns", value: N} dove N deve essere > 0 per mantenere gli ultimi N turni, o "all" per mantenere tutti i blocchi di pensiero. |
Configurazioni di esempio:
// 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"
}Combinazione di strategie
Puoi utilizzare sia la cancellazione dei blocchi di pensiero che la cancellazione dei risultati degli strumenti insieme:
Quando si utilizzano più strategie, la strategia clear_thinking_20251015 deve essere elencata per prima nell'array edits.
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
}
}
]
}
)Opzioni di configurazione per la cancellazione dei risultati degli strumenti
| Opzione di configurazione | Predefinito | Descrizione |
|---|---|---|
trigger | 100.000 token di input | Definisce quando la strategia di modifica del contesto si attiva. Una volta che il prompt supera questa soglia, la cancellazione avrà inizio. Puoi specificare questo valore in input_tokens o tool_uses. |
keep | 3 utilizzi di strumenti | Definisce quante coppie recenti di utilizzo/risultato degli strumenti mantenere dopo che si verifica la cancellazione. L'API rimuove prima le interazioni degli strumenti più vecchie, preservando le più recenti. |
clear_at_least | Nessuno | Garantisce che un numero minimo di token venga cancellato ogni volta che la strategia si attiva. Se l'API non riesce a cancellare almeno l'importo specificato, la strategia non verrà applicata. Questo aiuta a determinare se la cancellazione del contesto vale la pena di interrompere la cache del prompt. |
exclude_tools | Nessuno | Elenco dei nomi degli strumenti i cui utilizzi e risultati non devono mai essere cancellati. Utile per preservare il contesto importante. |
clear_tool_inputs | false | Controlla se i parametri della chiamata dello strumento vengono cancellati insieme ai risultati dello strumento. Per impostazione predefinita, vengono cancellati solo i risultati dello strumento mentre le chiamate dello strumento originali di Claude rimangono visibili. |
Risposta della modifica del contesto
Puoi vedere quali modifiche del contesto sono state applicate alla tua richiesta utilizzando il campo di risposta context_management, insieme a statistiche utili sul contenuto e sui token di input cancellati.
{
"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
}
]
}
}Per le risposte in streaming, le modifiche del contesto saranno incluse nell'evento finale message_delta:
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"stop_sequence": null
},
"usage": {
"output_tokens": 1024
},
"context_management": {
"applied_edits": [...]
}
}Conteggio dei token
L'endpoint di conteggio dei token supporta la gestione del contesto, permettendoti di visualizzare in anteprima quanti token utilizzerà 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": "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 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).
Utilizzo con lo strumento Memory
La modifica del contesto può essere combinata con lo strumento memory. Quando il contesto della tua conversazione si avvicina alla soglia di cancellazione configurata, Claude riceve un avviso automatico per preservare le informazioni importanti. Ciò consente a Claude di salvare i risultati degli strumenti o il contesto nei file di memoria prima che vengano cancellati dalla cronologia della conversazione.
Questa combinazione ti consente di:
- Preservare il contesto importante: Claude può scrivere informazioni essenziali dai risultati degli strumenti ai file di memoria prima che quei risultati vengano cancellati
- Mantenere flussi di lavoro di lunga durata: Abilita flussi di lavoro agentici che altrimenti supererebbero i limiti di contesto scaricando le informazioni su un'archiviazione persistente
- Accedere alle informazioni su richiesta: Claude può cercare le informazioni precedentemente cancellate dai file di memoria quando necessario, piuttosto che mantenere tutto nella finestra di contesto attiva
Ad esempio, in un flusso di lavoro di modifica dei file in cui Claude esegue molte operazioni, Claude può riassumere le modifiche completate nei file di memoria man mano che il contesto cresce. Quando i risultati degli strumenti vengono cancellati, Claude mantiene l'accesso a tali informazioni attraverso il suo sistema di memoria e può continuare a lavorare in modo efficace.
Per utilizzare entrambe le funzioni insieme, abilitale nella tua richiesta 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"}
]
}
)