Modifica del contesto

Panoramica

La modifica del contesto ti consente di cancellare selettivamente contenuti specifici dalla cronologia della conversazione man mano che cresce. Oltre a ottimizzare i costi e rimanere entro i limiti, si tratta di curare attivamente ciò che Claude vede: il contesto è una risorsa finita con rendimenti decrescenti, e il contenuto irrilevante degrada la messa a fuoco del modello. La modifica del contesto ti offre un controllo runtime granulare su quella cura. Per i principi più ampi dietro la gestione del contesto, vedi Effective context engineering. Questa pagina copre:

• Cancellazione dei risultati degli strumenti - Migliore per i flussi di lavoro agentici con uso intensivo di strumenti dove i vecchi risultati degli strumenti non sono più necessari
• Cancellazione dei blocchi di pensiero - Per gestire i blocchi di pensiero quando si utilizza il pensiero esteso, con opzioni per preservare il pensiero recente per la continuità del contesto
• Compattazione SDK lato client - Un'alternativa basata su SDK per la gestione del contesto basata su riepilogo (la compattazione lato server è generalmente preferita)

Strategie lato server

Cancellazione dei risultati degli strumenti

La strategia clear_tool_uses_20250919 cancella i risultati degli strumenti quando il contesto della conversazione cresce oltre la tua soglia configurata. Questo è particolarmente utile per i flussi di lavoro agentici con uso intensivo di strumenti. I vecchi risultati degli strumenti (come contenuti di file o risultati di ricerca) non sono più necessari una volta che Claude li ha elaborati.

Quando attivato, l'API cancella automaticamente i risultati degli strumenti più vecchi in ordine cronologico. L'API sostituisce ogni risultato cancellato con testo segnaposto in modo che Claude sappia che è stato rimosso. Per impostazione predefinita, vengono cancellati solo i risultati degli strumenti. Puoi facoltativamente cancellare sia i risultati degli strumenti che le chiamate degli 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 ti offre il controllo sulla preservazione del pensiero: puoi scegliere di mantenere più blocchi di pensiero per mantenere la continuità del ragionamento, o cancellarli più aggressivamente per risparmiare spazio di contesto.

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 tuo client con la versione modificata. Continua a gestire la tua cronologia completa della conversazione 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 tenere conto di ciò, cancella abbastanza token per rendere l'invalidazione della cache utile. Utilizza il parametro clear_at_least per 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 sono 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 sono cancellati, la cache viene invalidata nel punto in cui si verifica la cancellazione. Configura il parametro keep in 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 tutti i modelli Claude supportati.

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. Tutte le altre opzioni di configurazione utilizzano i loro valori predefiniti:

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"}]},
)

Configurazione avanzata

Puoi personalizzare il comportamento della cancellazione dei risultati degli strumenti con parametri aggiuntivi:

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"],
            }
        ]
    },
)

Utilizzo della cancellazione dei blocchi di pensiero

Abilita la cancellazione dei blocchi di pensiero per gestire efficacemente il contesto e la memorizzazione nella cache dei prompt quando il pensiero esteso è abilitato:

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},
            }
        ]
    },
)

Opzioni di configurazione per la cancellazione dei blocchi di pensiero

La strategia clear_thinking_20251015 supporta la seguente configurazione:

Configurazioni di esempio:

Mantieni i blocchi di pensiero degli ultimi 3 turni assistente:

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

Mantieni tutti i blocchi di pensiero (massimizza i cache hit):

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

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},
            },
        ]
    },
)

Opzioni di configurazione per la cancellazione dei risultati degli strumenti

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.

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 risposta mostra sia il conteggio dei token finale dopo che la gestione del contesto è stata applicata (input_tokens) che il conteggio dei token originale 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 conversazione si avvicina alla soglia di cancellazione configurata, Claude riceve un avviso automatico per preservare le informazioni importanti. Questo 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 nei file di memoria prima che questi risultati vengano cancellati
• Mantenere flussi di lavoro a lungo termine: Abilitare flussi di lavoro agentici che altrimenti supererebbero i limiti di contesto trasferendo le informazioni a un'archiviazione persistente
• Accedere alle informazioni su richiesta: Claude può cercare 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 di 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-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"}]},
)

Per il riferimento completo dello strumento memory inclusi comandi ed esempi, vedi Memory tool.

Compattazione lato client (SDK)

La compattazione è una funzione SDK che gestisce automaticamente il contesto della conversazione generando riassunti quando l'utilizzo dei token cresce troppo. A differenza delle strategie di modifica del contesto lato server che cancellano il contenuto, la compattazione istruisce Claude a riassumere la cronologia della conversazione, quindi sostituisce la cronologia completa con quel riassunto. Questo consente a Claude di continuare a lavorare su attività a lungo termine che altrimenti supererebbero la finestra di contesto.

Come funziona la compattazione

Quando la compattazione è abilitata, l'SDK monitora l'utilizzo dei token dopo ogni risposta del modello:

1. Controllo della soglia: L'SDK calcola i token totali come input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens.
2. Generazione del riassunto: Quando la soglia viene superata, un prompt di riassunto viene iniettato come turno dell'utente e Claude genera un riassunto strutturato avvolto in tag <summary></summary>.
3. Sostituzione del contesto: L'SDK estrae il riassunto e sostituisce l'intera cronologia dei messaggi con esso.
4. Continuazione: La conversazione riprende dal riassunto, con Claude che continua da dove era rimasto.

Utilizzo della compattazione

Aggiungi compaction_control alla tua chiamata tool_runner per abilitare il riassunto automatico quando l'utilizzo dei token supera la soglia.

Cosa accade durante la compattazione

Man mano che la conversazione cresce, la cronologia dei messaggi si accumula:

Prima della compattazione (avvicinandosi a 100k token):

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

Quando i token superano la soglia, l'SDK inietta una richiesta di riassunto e Claude genera un riassunto. L'intera cronologia viene quindi sostituita:

Dopo la compattazione (tornando a ~2-3k token):

[
  {
    "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 continua a lavorare da questo riassunto come se fosse la cronologia della conversazione originale.

Opzioni di configurazione

Scelta di una soglia di token

La soglia determina quando si verifica la compattazione. Una soglia più bassa significa compattazioni più frequenti con finestre di contesto più piccole. Una soglia più alta consente più contesto ma rischia di raggiungere i limiti.

# 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}

Utilizzo di un modello diverso per i riassunti

Puoi utilizzare un modello più veloce o più economico per generare i riassunti:

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

Prompt di riassunto personalizzati

Puoi fornire un prompt personalizzato per esigenze specifiche del dominio. Il tuo prompt dovrebbe istruire Claude a avvolgere il suo riassunto in tag <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.""",
}

Prompt di riassunto predefinito

Il prompt di riassunto integrato istruisce Claude a creare un riassunto di continuazione strutturato che includa:

1. Panoramica dell'attività: La richiesta principale dell'utente, i criteri di successo e i vincoli.
2. Stato attuale: Cosa è stato completato, file modificati e artefatti prodotti.
3. Scoperte importanti: Vincoli tecnici, decisioni prese, errori risolti e approcci falliti.
4. Passaggi successivi: Azioni specifiche necessarie, blocchi e ordine di priorità.
5. Contesto da preservare: Preferenze dell'utente, dettagli specifici del dominio e impegni presi.

Questa struttura consente a Claude di riprendere il lavoro in modo efficiente senza perdere il contesto importante o ripetere gli errori.

Limitazioni

Strumenti lato server

Quando si utilizzano strumenti lato server, l'SDK potrebbe calcolare in modo errato l'utilizzo dei token, causando l'attivazione della compattazione al momento sbagliato.

Ad esempio, dopo un'operazione di ricerca web, la risposta dell'API potrebbe mostrare:

{
  "usage": {
    "input_tokens": 63000,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

L'SDK calcola l'utilizzo totale come 63.000 + 270.000 = 333.000 token. Tuttavia, il valore cache_read_input_tokens include letture accumulate da più chiamate API interne effettuate dallo strumento lato server, non il tuo contesto di conversazione effettivo. La tua lunghezza di contesto reale potrebbe essere solo i 63.000 input_tokens, ma l'SDK vede 333k e attiva la compattazione prematuramente.

Soluzioni alternative:

• Usa l'endpoint di conteggio dei token per ottenere la lunghezza del contesto accurata
• Evita la compattazione quando utilizzi estensivamente strumenti lato server

Casi limite di utilizzo degli strumenti

Quando l'SDK attiva la compattazione mentre una risposta di utilizzo dello strumento è in sospeso, rimuove il blocco di utilizzo dello strumento dalla cronologia dei messaggi prima di generare il riassunto. Claude emetterà nuovamente la chiamata dello strumento dopo la ripresa dal riassunto se ancora necessaria.

Monitoraggio della compattazione

Comprendere quando si attiva la compattazione ti aiuta a regolare le soglie e verificare il comportamento previsto.

Quando utilizzare la compattazione

Buoni casi d'uso:

• Attività di agenti a lungo termine che elaborano molti file o fonti di dati
• Flussi di lavoro di ricerca che accumulano grandi quantità di informazioni
• Attività multi-step con progressi chiari e misurabili
• Attività che producono artefatti (file, report) che persistono al di fuori della conversazione

Casi d'uso meno ideali:

• Attività che richiedono il ricordo preciso dei dettagli della conversazione iniziale
• Flussi di lavoro che utilizzano estensivamente strumenti lato server
• Attività che devono mantenere lo stato esatto su molte variabili