Compattazione a una soglia di token

La "threshold compaction" (compattazione a soglia) è il tipo automatico di compattazione: imposti una "token threshold" (soglia di token) sulle tue richieste ordinarie e l'API riassume il contesto meno recente durante una richiesta, una volta raggiunta la soglia. È supportata insieme alla compattazione su richiesta, in cui sei tu a decidere quando viene scritto il riepilogo (consulta Compattazione su richiesta). Per scegliere tra le due, consulta Scegli come compattare.

La compattazione estende la lunghezza effettiva del contesto per conversazioni e attività di lunga durata, riassumendo automaticamente il contesto meno recente quando ci si avvicina al limite della "context window" (finestra di contesto). Mantiene inoltre ridotto il contesto attivo: man mano che una conversazione cresce, la qualità delle risposte peggiora, quindi la compattazione sostituisce il contenuto meno recente con un riepilogo conciso.

È ideale per:

• Conversazioni multi-turno basate su chat in cui vuoi che gli utenti usino una sola chat per un lungo periodo di tempo
• Prompt orientati alle attività che richiedono molto lavoro successivo (spesso uso degli strumenti) che potrebbe superare la finestra di contesto

Come funziona la compattazione

Quando la compattazione è abilitata, Claude riassume automaticamente la tua conversazione quando raggiunge la soglia di token configurata. L'API:

1. Rileva quando i token di input raggiungono la soglia di attivazione specificata.
2. Genera un riepilogo della conversazione corrente.
3. Crea un blocco compaction contenente il riepilogo.
4. Continua la risposta con il contesto compattato.

Nelle richieste successive, aggiungi la risposta ai tuoi messaggi. L'API elimina automaticamente tutti i blocchi di contenuto precedenti al blocco compaction, continuando la conversazione a partire dal riepilogo.

Utilizzo di base

Abilita la compattazione aggiungendo la strategia compact_20260112 a context_management.edits nella tua richiesta alla Messages API.

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Help me build a website"}]

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

# Aggiungi la risposta (incluso l'eventuale blocco di compattazione) per continuare la conversazione
messages.append({"role": "assistant", "content": response.content})

Parametri

Configurazione del trigger

Configura quando si attiva la compattazione usando il parametro trigger:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

Istruzioni di riepilogo personalizzate

Il prompt di riepilogo predefinito varia in base al modello. Ogni prompt predefinito indica a Claude di scrivere un riepilogo all'interno dei tag <summary></summary> con le informazioni necessarie per continuare l'attività in una futura finestra di contesto. Ad esempio, alcuni modelli usano il seguente prompt:

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

Puoi fornire istruzioni personalizzate tramite il parametro instructions. Le istruzioni personalizzate non integrano il prompt predefinito, ma lo sostituiscono completamente:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

Sui modelli Claude 5.1 e successivi, una richiesta con instructions personalizzate genera il riepilogo solo a partire dalla conversazione visibile: i blocchi di pensiero precedenti non fanno parte dell'input del processo di riepilogo.

Pausa dopo la compattazione

Usa pause_after_compaction per mettere in pausa l'API dopo la generazione del riepilogo di compattazione. Questo ti consente di aggiungere ulteriori blocchi di contenuto (ad esempio per preservare i messaggi recenti o specifici messaggi orientati alle istruzioni) prima che l'API continui con la risposta.

Quando è abilitato, l'API restituisce un messaggio con lo stop reason compaction dopo aver generato il blocco di compattazione:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Verifica se la compattazione ha attivato una pausa
if response.stop_reason == "compaction":
    # La risposta contiene solo il blocco di compattazione
    messages.append({"role": "assistant", "content": response.content})

    # Continua la richiesta
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

Applicare un budget totale di token

Quando un modello lavora su attività lunghe con molte iterazioni di uso degli strumenti, il consumo totale di token può crescere in modo significativo. Puoi combinare pause_after_compaction con un contatore di compattazioni per stimare l'utilizzo cumulativo e concludere l'attività in modo ordinato una volta raggiunto un budget.

Questo esempio è disponibile solo nei linguaggi degli SDK: il suo valore risiede nella logica di monitoraggio del budget attorno alla richiesta. La richiesta grezza combina il trigger di Configurazione del trigger con pause_after_compaction di Pausa dopo la compattazione.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD},
                "pause_after_compaction": True,
            }
        ]
    },
)

if response.stop_reason == "compaction":
    n_compactions += 1
    messages.append({"role": "assistant", "content": response.content})

    # Stima i token totali consumati; sollecita la chiusura se si supera il budget
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

Lavorare con i blocchi di compattazione

Quando viene attivata la compattazione, l'API restituisce un blocco compaction all'inizio della risposta dell'assistente.

Una conversazione di lunga durata potrebbe dare luogo a più compattazioni. L'ultimo blocco di compattazione riflette lo stato finale del prompt, sostituendo il contenuto che lo precede con il riepilogo generato.

{
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: The user requested help building a web scraper..."
    },
    {
      "type": "text",
      "text": "Based on our conversation so far..."
    }
  ]
}

Restituire i blocchi di compattazione

Devi restituire il blocco compaction all'API nelle richieste successive per continuare la conversazione con il prompt abbreviato. L'approccio più semplice è aggiungere l'intero contenuto della risposta ai tuoi messaggi:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# Dopo aver ricevuto una risposta con un blocco di compattazione
messages.append({"role": "assistant", "content": response.content})

# Continua la conversazione
messages.append({"role": "user", "content": "Now add error handling"})

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

In Python, usa client.beta.messages, come fanno gli esempi in questa pagina. Se chiami client.messages e serializzi i blocchi autonomamente, un semplice model_dump() aggiunge text: null e citations: null al blocco compaction. L'API rifiuta quindi la richiesta con un errore 400 (Extra inputs are not permitted). Usa invece to_dict() o model_dump(exclude_none=True). Continua dal riepilogo fornisce lo stesso consiglio per la compattazione su richiesta.

Quando l'API riceve un blocco compaction, tutti i blocchi di contenuto che lo precedono vengono ignorati. Puoi:

• Mantenere i messaggi originali nella tua lista e lasciare che sia l'API a gestire la rimozione del contenuto compattato
• Eliminare manualmente i messaggi compattati e includere solo i contenuti a partire dal blocco di compattazione

Su Claude Fable 5.1, Claude Mythos 5.1 e Claude Opus 5.5, i blocchi di pensiero precedenti a un blocco compaction non vengono riportati, quindi il riepilogo è tutto ciò che il modello conserva di quel lavoro precedente. Se scrivi le tue instructions, indica al modello cosa deve conservare il riepilogo; consulta Indica al modello cosa preservare nei riepiloghi di compattazione.

Streaming

Il blocco di compattazione viene trasmesso in streaming in modo diverso rispetto ai blocchi di testo. Ricevi un evento content_block_start, seguito da un singolo content_block_delta con il contenuto completo del riepilogo (senza streaming intermedio), e poi un evento content_block_stop.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]

with client.beta.messages.stream(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
    for event in stream:
        match event.type:
            case "content_block_start":
                block = event.content_block
                match block.type:
                    case "compaction":
                        print("Compaction started...")
                    case "text":
                        print("Text response started...")

            case "content_block_delta":
                delta = event.delta
                match delta.type:
                    case "compaction_delta":
                        print(f"Compaction complete: {len(delta.content or '')} chars")
                    case "text_delta":
                        print(delta.text, end="", flush=True)

    # Ottieni il messaggio finale accumulato
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Cache dei prompt

La compattazione funziona bene con il "prompt caching" (cache dei prompt). Puoi aggiungere un breakpoint cache_control sui blocchi di compattazione per memorizzare nella cache il contenuto riepilogato.

{
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "[summary text]",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Based on our conversation..."
    }
  ]
}

Massimizzare i cache hit con i prompt di sistema

Quando avviene una compattazione, il riepilogo diventa nuovo contenuto che deve essere scritto nella cache. Senza breakpoint di cache aggiuntivi, questo invaliderebbe anche qualsiasi "system prompt" (prompt di sistema) memorizzato nella cache, richiedendo di memorizzarlo nuovamente insieme al riepilogo di compattazione.

Per massimizzare il tasso di cache hit, aggiungi un breakpoint cache_control alla fine del tuo prompt di sistema. In questo modo il prompt di sistema resta memorizzato nella cache separatamente dalla conversazione, quindi quando avviene una compattazione:

• La cache del prompt di sistema rimane valida e viene letta dalla cache
• Solo il riepilogo di compattazione deve essere scritto come nuova voce della cache

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    max_tokens=4096,
    system=[
        {
            "type": "text",
            "text": "You are a helpful coding assistant...",
            "cache_control": {
                "type": "ephemeral"
            },  # Cache the system prompt separately
        }
    ],
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

In questo modo i prompt di sistema lunghi restano memorizzati nella cache attraverso più eventi di compattazione nel corso di una conversazione.

Comprendere l'utilizzo

La compattazione richiede un passaggio di campionamento aggiuntivo, che incide sui "rate limit" (limiti di velocità) e sulla fatturazione. L'API restituisce informazioni dettagliate sull'utilizzo nella risposta:

{
  "usage": {
    "input_tokens": 23000,
    "output_tokens": 1000,
    "iterations": [
      {
        "type": "compaction",
        "input_tokens": 180000,
        "output_tokens": 3500
      },
      {
        "type": "message",
        "input_tokens": 23000,
        "output_tokens": 1000
      }
    ]
  }
}

L'array iterations mostra l'utilizzo per ogni iterazione di campionamento. Quando avviene una compattazione, vedrai un'iterazione compaction seguita dall'iterazione principale message. In questo esempio, i valori di primo livello input_tokens e output_tokens corrispondono esattamente all'iterazione message perché c'è una sola iterazione non di compattazione. I conteggi dei token dell'iterazione finale riflettono la dimensione effettiva del contesto dopo la compattazione.

Combinazione con altre funzionalità

Strumenti server

Quando usi strumenti server (come la ricerca web), il trigger di compattazione viene verificato all'inizio di ogni iterazione di campionamento. La compattazione potrebbe avvenire più volte all'interno di una singola richiesta, a seconda della soglia di attivazione e della quantità di output generato.

Conteggio dei token

L'endpoint di conteggio dei token (/v1/messages/count_tokens) applica i blocchi compaction esistenti nel tuo prompt, ma non attiva nuove compattazioni. Usalo per verificare il conteggio effettivo dei token dopo le compattazioni precedenti:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-5-5",
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

print(f"Current tokens: {count_response.input_tokens}")
print(f"Original tokens: {count_response.context_management.original_input_tokens}")

Esempi

Ecco un esempio completo di una conversazione di lunga durata con compattazione:

client = anthropic.Anthropic()

messages: list[dict] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Aggiungi la risposta (i blocchi di compattazione sono inclusi automaticamente)
    messages.append({"role": "assistant", "content": response.content})

    # Restituisci il contenuto testuale
    return next(block.text for block in response.content if block.type == "text")


# Esegui una conversazione lunga
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# Continua a chiamare chat() finché la conversazione lo richiede

Su Claude Fable 5.1 e Claude Opus 5.5, rimuovi i blocchi thinking e redacted_thinking da qualsiasi turno dell'assistente che reinserisci dopo il blocco di compattazione, oppure invia thinking.block_binding.prefix_mismatch_behavior: "drop_block" con l'header beta thinking-binding-controls-2026-08-01. Quei blocchi sono stati prodotti quando era presente la cronologia completa, quindi non superano più il controllo della conversazione. Dove il controllo è applicato, la richiesta di continuazione viene rifiutata con un errore 400. I blocchi di testo e di strumenti preservati possono restare invariati. Lasciare che l'API riassuma tutto, senza reinserire i turni precedenti, evita questo problema.

Ecco un esempio che usa pause_after_compaction per preservare alla lettera lo scambio precedente e il messaggio corrente dell'utente (tre messaggi in totale) invece di riassumerli:

from typing import Any

client = anthropic.Anthropic()

messages: list[dict[str, Any]] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Verifica se la compattazione è avvenuta e si è messa in pausa
    if response.stop_reason == "compaction":
        # Ottieni il blocco di compattazione dalla risposta
        compaction_block = response.content[0]

        # Conserva lo scambio precedente + il messaggio utente corrente (3 messaggi)
        # includendoli dopo il blocco di compattazione
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Crea il nuovo elenco di messaggi: compattazione + messaggi conservati
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Prosegui la richiesta con il contesto compattato + i messaggi conservati
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-5-5",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Aggiorna l'elenco dei messaggi per riflettere la compattazione
        messages.clear()
        messages.extend(messages_after_compaction)

    # Aggiungi la risposta finale
    messages.append({"role": "assistant", "content": response.content})

    # Restituisci il contenuto testuale
    return next(block.text for block in response.content if block.type == "text")


# Esegui una conversazione lunga
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# Continua a chiamare chat() finché la conversazione lo richiede

Limitazioni attuali

• Stesso modello per il riepilogo: il modello specificato nella tua richiesta viene usato per il riepilogo. Non è possibile usare un modello diverso (ad esempio, più economico) per il riepilogo.

• La compattazione potrebbe non riuscire quando sono definiti strumenti: quando la tua richiesta include tools, il modello occasionalmente chiama uno strumento durante il passaggio interno di riepilogo invece di scrivere un riepilogo. Quando ciò accade, la risposta contiene un blocco compaction con content: null. Per evitarlo, imposta instructions su un prompt che indichi esplicitamente al modello di non chiamare strumenti, ad esempio:

  Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only.

  

Passaggi successivi

Compatibility