Modifica del contesto

Panoramica

La modifica del contesto ti consente di rimuovere 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 i contenuti irrilevanti degradano la concentrazione del modello. La modifica del contesto ti offre un controllo granulare a runtime su tale curazione. Per i principi più ampi alla base della gestione del contesto, consulta Effective context engineering. Questa pagina tratta:

• Rimozione dei risultati degli strumenti - Ideale per flussi di lavoro agentici con uso intensivo degli strumenti in cui i vecchi risultati degli strumenti non sono più necessari
• Rimozione 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 tramite riepilogo (la compattazione lato server è generalmente preferibile)

Strategie lato server

Rimozione dei risultati degli strumenti

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

Quando attivata, l'API rimuove automaticamente i risultati degli strumenti più vecchi in ordine cronologico. L'API sostituisce ogni risultato rimosso con un testo segnaposto in modo che Claude sappia che è stato rimosso. Per impostazione predefinita, vengono rimossi solo i risultati degli strumenti. Puoi opzionalmente rimuovere sia i risultati degli strumenti sia le chiamate agli strumenti (i parametri di uso degli strumenti) impostando clear_tool_inputs su true.

Rimozione 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 conservazione del pensiero: puoi scegliere di mantenere più blocchi di pensiero per preservare la continuità del ragionamento, oppure rimuoverli in modo più aggressivo per risparmiare spazio nel contesto.

Un turno di conversazione dell'assistente può includere più blocchi di contenuto (ad esempio, quando si utilizzano strumenti) e più blocchi di pensiero (ad esempio, con il 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 localmente la cronologia completa della conversazione come faresti normalmente.

Modifica del contesto e cache dei prompt

L'interazione della modifica del contesto con la cache dei prompt varia in base alla strategia:

• Rimozione dei risultati degli strumenti: Invalida i prefissi dei prompt memorizzati nella cache quando il contenuto viene rimosso. Per tenerne conto, rimuovi un numero sufficiente di token da rendere conveniente l'invalidazione della cache. Usa il parametro clear_at_least per garantire che venga rimosso un numero minimo di token ogni volta. Sosterrai costi di scrittura nella cache ogni volta che il contenuto viene rimosso, ma le richieste successive possono riutilizzare il prefisso appena memorizzato nella cache.

• Rimozione dei blocchi di pensiero: Quando i blocchi di pensiero vengono mantenuti nel contesto (non rimossi), la cache dei prompt viene preservata, consentendo cache hit e riducendo i costi dei token di input. Quando i blocchi di pensiero vengono rimossi, la cache viene invalidata nel punto in cui avviene la rimozione. Configura il parametro keep in base a se vuoi 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 rimozione dei risultati degli strumenti

Il modo più semplice per abilitare la rimozione 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-8",
    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 rimozione dei risultati degli strumenti con parametri aggiuntivi:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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",
                # Attiva la cancellazione quando la soglia viene superata
                "trigger": {"type": "input_tokens", "value": 30000},
                # Numero di usi degli strumenti da conservare dopo la cancellazione
                "keep": {"type": "tool_uses", "value": 3},
                # Opzionale: cancella almeno questo numero di token
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Escludi questi strumenti dalla cancellazione
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

Utilizzo della rimozione dei blocchi di pensiero

Abilita la rimozione dei blocchi di pensiero per gestire efficacemente il contesto e la 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 rimozione dei blocchi di pensiero

La strategia clear_thinking_20251015 supporta la seguente configurazione:

Esempi di configurazione:

Mantieni i blocchi di pensiero degli ultimi 3 turni dell'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"
}

Combinare le strategie

Puoi utilizzare insieme sia la rimozione dei blocchi di pensiero sia la rimozione dei risultati degli strumenti:

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 rimozione 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 rimossi.

{
  "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, consentendoti di visualizzare in anteprima quanti token utilizzerà il tuo prompt dopo l'applicazione della modifica del contesto.

response = client.beta.messages.count_tokens(
    model="claude-opus-4-8",
    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 finale dei token dopo l'applicazione della gestione del contesto (input_tokens) sia il conteggio originale dei token prima di qualsiasi rimozione (original_input_tokens).

Utilizzo con lo strumento di memoria

La modifica del contesto può essere combinata con lo strumento di memoria. Quando il contesto della conversazione si avvicina alla soglia di rimozione 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 suoi file di memoria prima che vengano rimossi dalla cronologia della conversazione.

Questa combinazione ti consente di:

• Preservare contesto importante: Claude può scrivere informazioni essenziali dai risultati degli strumenti nei file di memoria prima che tali risultati vengano rimossi
• Mantenere flussi di lavoro di lunga durata: Abilitare flussi di lavoro agentici che altrimenti supererebbero i limiti di contesto trasferendo le informazioni in uno storage persistente
• Accedere alle informazioni su richiesta: Claude può recuperare informazioni precedentemente rimosse dai file di memoria quando necessario, invece di 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 rimossi, 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 funzionalità insieme, abilitale nella tua richiesta API:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[...],
    tools=[
        {"type": "memory_20250818", "name": "memory"},
        # I tuoi altri strumenti
    ],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

Per il riferimento completo dello strumento di memoria, inclusi comandi ed esempi, consulta Strumento di memoria.

Compattazione lato client (SDK)

La compattazione è una funzionalità SDK che gestisce automaticamente il contesto della conversazione generando riepiloghi quando l'utilizzo dei token diventa troppo elevato. A differenza delle strategie di modifica del contesto lato server che rimuovono contenuti, la compattazione istruisce Claude a riassumere la cronologia della conversazione, quindi sostituisce l'intera cronologia con tale riepilogo. Questo consente a Claude di continuare a lavorare su attività di lunga durata 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. Verifica della soglia: L'SDK calcola i token totali come input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens.
2. Generazione del riepilogo: Quando la soglia viene superata, un prompt di riepilogo viene iniettato come turno utente e Claude genera un riepilogo strutturato racchiuso in tag <summary></summary>.
3. Sostituzione del contesto: L'SDK estrae il riepilogo e sostituisce l'intera cronologia dei messaggi con esso.
4. Continuazione: La conversazione riprende dal riepilogo, con Claude che riprende da dove si era interrotto.

Utilizzo della compattazione

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

Cosa succede 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 riepilogo e Claude genera un riepilogo. L'intera cronologia viene quindi sostituita:

Dopo la compattazione (di nuovo 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 riepilogo come se fosse la cronologia originale della conversazione.

Opzioni di configurazione

Scegliere una soglia di token

La soglia determina quando avviene 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.

# Compattazione più frequente per scenari con memoria limitata
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# Compattazione meno frequente quando serve più contesto
compaction_control = {"enabled": True, "context_token_threshold": 150000}

Utilizzare un modello diverso per i riepiloghi

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

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

Prompt di riepilogo personalizzati

Puoi fornire un prompt personalizzato per esigenze specifiche del dominio. Il tuo prompt dovrebbe istruire Claude a racchiudere il suo riepilogo 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 riepilogo predefinito

Il prompt di riepilogo integrato istruisce Claude a creare un riepilogo strutturato di continuazione che include:

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. Prossimi passi: 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 contesto importante o ripetere 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_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

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

Soluzioni alternative:

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

Casi limite dell'uso degli strumenti

Quando l'SDK attiva la compattazione mentre una risposta di uso degli strumenti è in sospeso, rimuove il blocco di uso degli strumenti dalla cronologia dei messaggi prima di generare il riepilogo. Claude riemetterà la chiamata allo strumento dopo aver ripreso dal riepilogo, se ancora necessaria.

Monitoraggio della compattazione

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

Quando usare la compattazione

Casi d'uso appropriati:

• Attività di agenti di lunga durata 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 un richiamo preciso dei dettagli iniziali della conversazione
• Flussi di lavoro che utilizzano intensivamente strumenti lato server
• Attività che devono mantenere uno stato esatto su molte variabili