Compattazione

La compattazione lato server è la strategia consigliata per gestire il contesto in conversazioni di lunga durata e flussi di lavoro agentici. Gestisce automaticamente la gestione del contesto con un lavoro di integrazione minimo.

La compattazione estende la lunghezza effettiva del contesto per conversazioni e attività di lunga durata riassumendo automaticamente il contesto più vecchio quando ci si avvicina al limite della finestra di contesto. Questo è ideale per:

Conversazioni basate su chat, multi-turno dove vuoi che gli utenti utilizzino una chat per un lungo periodo di tempo
Prompt orientati alle attività che richiedono molto lavoro di follow-up (spesso uso di strumenti) che potrebbe superare la finestra di contesto di 200K

La compattazione è attualmente in beta. Includi l'intestazione beta compact-2026-01-12 nelle tue richieste API per utilizzare questa funzione.

This feature is in beta and is not covered by Zero Data Retention (ZDR) arrangements. Beta features are excluded from ZDR.

Modelli supportati

La compattazione è supportata sui seguenti modelli:

Claude Opus 4.6 (claude-opus-4-6)

Come funziona la compattazione

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

Rileva quando i token di input superano la soglia di attivazione specificata.
Genera un riassunto della conversazione attuale.
Crea un blocco compaction contenente il riassunto.
Continua la risposta con il contesto compattato.

Nelle richieste successive, aggiungi la risposta ai tuoi messaggi. L'API elimina automaticamente tutti i blocchi di messaggi prima del blocco compaction, continuando la conversazione dal riassunto.

Diagramma di flusso che mostra il processo di compattazione: quando i token di input superano la soglia di attivazione, Claude genera un riassunto in un blocco di compattazione e continua la risposta con il contesto compattato

Utilizzo di base

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

Parametri

Parametro	Tipo	Predefinito	Descrizione
`type`	string	Obbligatorio	Deve essere `"compact_20260112"`
`trigger`	object	150.000 token	Quando attivare la compattazione. Deve essere almeno 50.000 token.
`pause_after_compaction`	boolean	`false`	Se mettere in pausa dopo aver generato il riassunto di compattazione
`instructions`	string	`null`	Prompt di riassunto personalizzato. Sostituisce completamente il prompt predefinito quando fornito.

Configurazione del trigger

Configura quando la compattazione si attiva utilizzando il parametro trigger:

Istruzioni di riassunto personalizzate

Per impostazione predefinita, la compattazione utilizza il seguente prompt di riassunto:

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 per sostituire completamente questo prompt. Le istruzioni personalizzate non integrano il valore predefinito; lo sostituiscono completamente:

Pausa dopo la compattazione

Utilizza pause_after_compaction per mettere in pausa l'API dopo aver generato il riassunto di compattazione. Questo ti consente di aggiungere blocchi di contenuto aggiuntivi (come preservare messaggi recenti o messaggi specifici orientati alle istruzioni) prima che l'API continui con la risposta.

Quando abilitato, l'API restituisce un messaggio con il motivo di arresto compaction dopo aver generato il blocco di compattazione:

Applicazione di un budget totale di token

Quando un modello lavora su attività lunghe con molte iterazioni di uso di strumenti, il consumo totale di token può crescere significativamente. Puoi combinare pause_after_compaction con un contatore di compattazione per stimare l'utilizzo cumulativo e concludere elegantemente l'attività una volta raggiunto un budget:

Python

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

    # Estimate total tokens consumed; prompt wrap-up if over 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.",
            }
        )

Utilizzo dei blocchi di compattazione

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

Una conversazione di lunga durata può risultare in più compattazioni. L'ultimo blocco di compattazione riflette lo stato finale del prompt, sostituendo il contenuto precedente con il riassunto 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..."
    }
  ]
}

Passaggio dei blocchi di compattazione

Devi passare 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:

Quando l'API riceve un blocco compaction, tutti i blocchi di contenuto prima di esso vengono ignorati. Puoi:

Mantenere i messaggi originali nel tuo elenco e lasciare che l'API gestisca la rimozione del contenuto compattato
Eliminare manualmente i messaggi compattati e includere solo il blocco di compattazione in poi

Streaming

Quando si esegue lo streaming di risposte con la compattazione abilitata, riceverai un evento content_block_start quando la compattazione inizia. Il blocco di compattazione viene trasmesso diversamente dai blocchi di testo. Riceverai un evento content_block_start, seguito da un singolo content_block_delta con il contenuto di riepilogo completo (nessuno streaming intermedio), e quindi un evento content_block_stop.

Caching del prompt

La compattazione funziona bene con il caching del prompt. Puoi aggiungere un punto di interruzione cache_control sui blocchi di compattazione per memorizzare nella cache il contenuto riassunto. Il contenuto compattato originale viene ignorato.

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

Massimizzazione dei hit della cache con i prompt di sistema

Quando si verifica la compattazione, il riassunto diventa nuovo contenuto che deve essere scritto nella cache. Senza punti di interruzione della cache aggiuntivi, questo invaliderebbe anche qualsiasi prompt di sistema memorizzato nella cache, richiedendo che venga memorizzato nuovamente nella cache insieme al riassunto di compattazione.

Per massimizzare i tassi di hit della cache, aggiungi un punto di interruzione cache_control alla fine del tuo prompt di sistema. Questo mantiene il prompt di sistema memorizzato nella cache separatamente dalla conversazione, quindi quando si verifica la compattazione:

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

Questo approccio è particolarmente vantaggioso per i prompt di sistema lunghi, poiché rimangono memorizzati nella cache anche attraverso più eventi di compattazione durante una conversazione.

Comprensione dell'utilizzo

La compattazione richiede un passaggio di campionamento aggiuntivo, che contribuisce ai limiti di velocità e alla fatturazione. L'API restituisce informazioni di utilizzo dettagliate nella risposta:

{
  "usage": {
    "input_tokens": 45000,
    "output_tokens": 1234,
    "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 si verifica la compattazione, vedrai un'iterazione compaction seguita dall'iterazione principale message. I conteggi dei token dell'iterazione finale riflettono la dimensione effettiva del contesto dopo la compattazione.

I input_tokens e output_tokens di livello superiore non includono l'utilizzo dell'iterazione di compattazione—riflettono la somma di tutte le iterazioni non di compattazione. Per calcolare i token totali consumati e fatturati per una richiesta, somma tutti gli elementi nell'array usage.iterations.

Se in precedenza hai fatto affidamento su usage.input_tokens e usage.output_tokens per il tracciamento dei costi o il controllo, dovrai aggiornare la tua logica di tracciamento per aggregare tra usage.iterations quando la compattazione è abilitata. L'array iterations viene popolato solo quando una nuova compattazione viene attivata durante la richiesta. La riapplicazione di un precedente blocco compaction non comporta costi di compattazione aggiuntivi, e i campi di utilizzo di livello superiore rimangono accurati in quel caso.

Combinazione con altre funzioni

Strumenti server

Quando si utilizzano strumenti server (come la ricerca web), il trigger di compattazione viene controllato all'inizio di ogni iterazione di campionamento. La compattazione può verificarsi più volte all'interno di una singola richiesta a seconda della tua 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 tuo conteggio di token effettivo dopo le compattazioni precedenti:

Esempi

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

Ecco un esempio che utilizza pause_after_compaction per preservare gli ultimi due messaggi (un turno utente + uno assistente) verbatim invece di riassumerli:

Limitazioni attuali

Stesso modello per il riassunto: Il modello specificato nella tua richiesta viene utilizzato per il riassunto. Non c'è opzione per utilizzare un modello diverso (ad esempio, più economico) per il riassunto.

Passaggi successivi

Compaction cookbook

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: compact-2026-01-12" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-6",
    "max_tokens": 4096,
    "messages": [
        {
            "role": "user",
            "content": "Help me build a website"
        }
    ],
    "context_management": {
        "edits": [
            {
                "type": "compact_20260112"
            }
        ]
    }
}'

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

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

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

# Check if compaction triggered a pause
if response.stop_reason == "compaction":
    # Response contains only the compaction block
    messages.append({"role": "assistant", "content": response.content})

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

# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})

# Continue the conversation
messages.append({"role": "user", "content": "Now add error handling"})

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

import anthropic

client = anthropic.Anthropic()

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

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

    # Get the final accumulated message
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-6",
    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"}]},
)

count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-6",
    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}")

import anthropic

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-4-6",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Append response (compaction blocks are automatically included)
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
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"))
# ... continue as long as needed

import anthropic
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-4-6",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Check if compaction occurred and paused
    if response.stop_reason == "compaction":
        # Get the compaction block from the response
        compaction_block = response.content[0]

        # Preserve the last 2 messages (1 user + 1 assistant turn)
        # by including them after the compaction block
        preserved_messages = messages[-2:] if len(messages) >= 2 else messages

        # Build new message list: compaction + preserved messages
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Continue the request with the compacted context + preserved messages
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-6",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Update our message list to reflect the compaction
        messages.clear()
        messages.extend(messages_after_compaction)

    # Append the final response
    messages.append({"role": "assistant", "content": response.content})

    # Return the text content
    return next(block.text for block in response.content if block.type == "text")


# Run a long conversation
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"))
# ... continue as long as needed