Compattazione

CostruisciGestione del contesto

Compaction

Compattazione del contesto lato server per gestire conversazioni lunghe che si avvicinano ai limiti della finestra di contesto.

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

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. Non si tratta solo di stare sotto un limite di token. Man mano che le conversazioni si allungano, i modelli faticano a mantenere la concentrazione su tutta la cronologia. La compattazione mantiene il contesto attivo focalizzato e performante sostituendo il contenuto obsoleto con riassunti concisi.

Per un'analisi più approfondita del motivo per cui i contesti lunghi si degradano e come la compattazione aiuta, consulta Effective context engineering.

Questo è ideale per:

Conversazioni basate su chat, multi-turno in cui desideri 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

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

Modelli supportati

La compattazione è supportata sui seguenti modelli:

Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-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 corrente.
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.

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

# Append the response (including any compaction block) to continue the conversation
messages.append({"role": "assistant", "content": response.content})

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 la generazione del 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:

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

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:

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

Pausa dopo la compattazione

Usa pause_after_compaction per mettere in pausa l'API dopo aver generato il riepilogo della compattazione. Questo ti consente di aggiungere blocchi di contenuto aggiuntivi (come la conservazione dei 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:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    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-7",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

Applicazione di un budget totale di token

Quando un modello lavora su attività lunghe con molte iterazioni di utilizzo 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

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-4-7",
    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 riepilogo generato.

Output

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

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    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-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

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 inizia la compattazione. 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 del riepilogo completo (nessuno streaming intermedio), e quindi 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-4-7",
    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})

Compressione della cache

La compressione funziona bene con la compressione della cache. Puoi aggiungere un punto di interruzione cache_control sui blocchi di compressione per memorizzare nella cache il contenuto riassunto. Il contenuto compresso originale viene ignorato.

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

Massimizzare i risultati della cache con i prompt di sistema

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

Per massimizzare i tassi di risultati 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 compressione:

La cache del prompt di sistema rimane valida e viene letta dalla cache
Solo il riassunto della compressione 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-4-7",
    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"}]},
)

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

Comprensione dell'utilizzo

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

Output

{
  "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 si verifica la compressione, vedrai un'iterazione compaction seguita dall'iterazione principale message. I input_tokens e output_tokens di livello superiore corrispondono esattamente all'iterazione message in questo esempio perché c'è solo un'iterazione non di compressione. I conteggi dei token dell'iterazione finale riflettono la dimensione effettiva del contesto dopo la compressione.

I input_tokens e output_tokens di livello superiore non includono l'utilizzo dell'iterazione di compressione. Riflettono la somma di tutte le iterazioni non di compressione. 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 compressione è abilitata. L'array iterations viene popolato solo quando viene attivata una nuova compressione durante la richiesta. La riapplicazione di un blocco compaction precedente non comporta costi di compressione aggiuntivi e i campi di utilizzo di livello superiore rimangono accurati in quel caso.

Combinazione con altre funzionalità

Strumenti server

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

Ecco un esempio che utilizza pause_after_compaction per preservare lo scambio precedente e il messaggio utente corrente (tre messaggi totali) verbatim 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-4-7",
        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 prior exchange + current user message (3 messages)
        # by including them after the compaction block
        preserved_messages = messages[-3:] if len(messages) >= 3 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-7",
            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

Limitazioni attuali

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

Passaggi successivi

Compattazione della memoria di sessione cookbook

Esplora un'implementazione pratica che gestisce conversazioni di lunga durata con compattazione istantanea della memoria di sessione utilizzando threading in background e caching dei prompt.

Finestre di contesto

Scopri le dimensioni delle finestre di contesto e le strategie di gestione.

Modifica del contesto

Esplora altre strategie per gestire il contesto della conversazione come la cancellazione dei risultati degli strumenti e la cancellazione dei blocchi di pensiero.

Was this page helpful?

CostruisciGestione del contesto

Compaction

Compattazione del contesto lato server per gestire conversazioni lunghe che si avvicinano ai limiti della finestra di contesto.

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Per un'analisi più approfondita del motivo per cui i contesti lunghi si degradano e come la compattazione aiuta, consulta Effective context engineering.

Questo è ideale per:

Conversazioni basate su chat, multi-turno in cui desideri 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

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

Modelli supportati

La compattazione è supportata sui seguenti modelli:

Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-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 corrente.
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.

Utilizzo di base

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

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

# Append the response (including any compaction block) to continue the conversation
messages.append({"role": "assistant", "content": response.content})

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 la generazione del 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:

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

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.

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

Pausa dopo la compattazione

Quando abilitato, l'API restituisce un messaggio con il motivo di arresto 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-4-7",
    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-7",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

Applicazione di un budget totale di token

Python

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-4-7",
    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.

Output

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

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    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-7",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

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

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

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

Compressione della cache

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

Massimizzare i risultati della cache con i prompt di sistema

La cache del prompt di sistema rimane valida e viene letta dalla cache
Solo il riassunto della compressione 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-4-7",
    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"}]},
)

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

Comprensione dell'utilizzo

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

Output

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

Combinazione con altre funzionalità

Strumenti server

Conteggio dei token

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-7",
    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-4-7",
        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

Ecco un esempio che utilizza pause_after_compaction per preservare lo scambio precedente e il messaggio utente corrente (tre messaggi totali) verbatim 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-4-7",
        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 prior exchange + current user message (3 messages)
        # by including them after the compaction block
        preserved_messages = messages[-3:] if len(messages) >= 3 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-7",
            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

Limitazioni attuali

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

Passaggi successivi

Compattazione della memoria di sessione cookbook

Esplora un'implementazione pratica che gestisce conversazioni di lunga durata con compattazione istantanea della memoria di sessione utilizzando threading in background e caching dei prompt.

Finestre di contesto

Scopri le dimensioni delle finestre di contesto e le strategie di gestione.

Modifica del contesto

Esplora altre strategie per gestire il contesto della conversazione come la cancellazione dei risultati degli strumenti e la cancellazione dei blocchi di pensiero.

Was this page helpful?