MessaggiGestione del contesto

Compattazione

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

Questa funzionalità è idonea per la Zero Data Retention (ZDR). Quando la tua organizzazione dispone di un accordo ZDR, i dati inviati tramite questa funzionalità non vengono conservati dopo che la risposta dell'API è stata restituita.

La compattazione lato server è la strategia consigliata per gestire il contesto nelle conversazioni di lunga durata e nei flussi di lavoro agentici. Gestisce automaticamente il contesto, senza codice di riepilogo lato client.

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 "context window" (finestra di contesto). Mantiene inoltre ridotto il contesto attivo: man mano che una conversazione cresce, la qualità delle risposte si degrada, quindi la compattazione sostituisce il contenuto più vecchio con un riepilogo conciso.

Per un approfondimento sul perché i contesti lunghi si degradano e su come la compattazione aiuta, consulta Effective context engineering.

Questo è ideale per:

Conversazioni multi-turno basate su chat in cui desideri che gli utenti utilizzino una singola chat per un lungo periodo di tempo
Prompt orientati ad attività che richiedono molto lavoro di follow-up (spesso uso degli strumenti) che potrebbe superare la finestra di contesto

La compattazione è in beta. Includi il beta header compact-2026-01-12 nelle tue richieste API per utilizzare questa funzionalità.

Modelli supportati

La compattazione è supportata sui seguenti modelli:

Claude Fable 5 (claude-fable-5)
Claude Mythos 5 (claude-mythos-5)
Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)

Come funziona la compattazione

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

Rileva quando i token di input raggiungono la soglia di attivazione specificata.
Genera un riepilogo della conversazione corrente.
Crea un blocco compaction contenente il riepilogo.
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 dal riepilogo.

Flusso di compattazione: quando i token di input raggiungono il trigger, Claude scrive un riepilogo in un blocco di compattazione e continua

Utilizzo di base

Abilita la compattazione aggiungendo la strategia compact_20260112 a context_management.edits nella tua richiesta all'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-8",
    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

Parametro	Tipo	Predefinito	Descrizione
`type`	string	Obbligatorio	Deve essere `"compact_20260112"`
`trigger`	object	`{"type": "input_tokens", "value": 150000}`	Quando attivare la compattazione. `input_tokens` è l'unico tipo di trigger supportato. `value` deve essere almeno 50.000 token.
`pause_after_compaction`	boolean	`false`	Se mettere in pausa dopo aver generato il riepilogo di compattazione
`instructions`	string	`null`	Prompt di riepilogo personalizzato. Sostituisce completamente il prompt predefinito quando fornito.

Configurazione del trigger

Configura quando si attiva la compattazione 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-8",
    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 istruisce Claude a scrivere un riepilogo all'interno di tag <summary></summary> con le informazioni necessarie per continuare l'attività in una futura finestra di contesto. Ad esempio, alcuni modelli utilizzano 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. 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-8",
    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 di compattazione. Questo ti consente di aggiungere blocchi di contenuto aggiuntivi (come preservare i messaggi recenti o messaggi specifici 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-4-8",
    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-4-8",
        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 compattazione per stimare l'utilizzo cumulativo e concludere l'attività in modo ordinato una volta raggiunto un budget.

Questo esempio appare solo nei linguaggi SDK: il suo valore risiede nella logica di tracciamento del budget attorno alla richiesta. La richiesta grezza combina il trigger da Configurazione del trigger con pause_after_compaction da 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-4-8",
    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 conclusione se oltre 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 comportare 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..."
    }
  ]
}

Passare i blocchi di compattazione all'API

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

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

Mantenere i messaggi originali nella tua lista 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

Il blocco di compattazione viene trasmesso in streaming in modo diverso dai 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-4-8",
    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 or '')} chars")
            elif event.delta.type == "text_delta":
                print(event.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 la cache dei prompt. Puoi aggiungere un breakpoint cache_control sui blocchi di compattazione per memorizzare nella cache il contenuto riassunto.

{
  "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 si verifica la compattazione, il riepilogo diventa nuovo contenuto che deve essere scritto nella cache. Senza breakpoint di cache aggiuntivi, questo invaliderebbe anche qualsiasi prompt di sistema memorizzato nella cache, richiedendo che venga nuovamente memorizzato insieme al riepilogo di compattazione.

Per massimizzare i tassi di cache hit, aggiungi un breakpoint cache_control alla fine del tuo prompt di sistema. Questo mantiene il prompt di sistema memorizzato nella cache separatamente dalla conversazione, così quando si verifica la 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 di cache

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    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 mantiene i prompt di sistema lunghi memorizzati nella cache attraverso più eventi di compattazione durante una conversazione.

Comprendere l'utilizzo

La compattazione richiede un passaggio di campionamento aggiuntivo, che contribuisce ai limiti di velocità e alla fatturazione. L'API restituisce informazioni dettagliate sull'utilizzo 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 compattazione, vedrai un'iterazione compaction seguita dall'iterazione principale message. I valori di primo livello input_tokens e output_tokens corrispondono esattamente all'iterazione message in questo esempio perché c'è solo un'iterazione non di compattazione. I conteggi dei token dell'iterazione finale riflettono la dimensione effettiva del contesto dopo la compattazione.

I valori di primo livello input_tokens e output_tokens non includono l'utilizzo dell'iterazione di compattazione. Riflettono la somma di tutte le iterazioni non di compattazione. Per calcolare il totale dei token consumati e fatturati per una richiesta, somma tutte le voci nell'array usage.iterations.

Se in precedenza ti affidavi a usage.input_tokens e usage.output_tokens per il tracciamento dei costi o l'auditing, dovrai aggiornare la tua logica di tracciamento per aggregare su usage.iterations quando la compattazione è abilitata. Con la beta di compattazione abilitata, ogni risposta include usage.iterations, anche se non si è verificata alcuna compattazione. Una voce compaction appare solo quando viene attivata una nuova compattazione durante la richiesta. Riapplicare un blocco compaction precedente non comporta costi di compattazione aggiuntivi, e in quel caso i campi di utilizzo di primo livello rimangono accurati.

Combinazione con altre funzionalità

Strumenti server

Quando si utilizzano strumenti server (come la ricerca web), il trigger di compattazione viene verificato all'inizio di ogni iterazione di campionamento. La compattazione potrebbe verificarsi più volte all'interno di una singola richiesta a seconda della 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 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-4-8",
    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-8",
        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() per tutto il tempo necessario alla conversazione

Ecco un esempio che utilizza pause_after_compaction per preservare lo scambio precedente e il messaggio utente corrente (tre messaggi in totale) alla lettera 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-8",
        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

        # Costruisci la nuova lista di messaggi: compattazione + messaggi conservati
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

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

        # Aggiorna la nostra lista di 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() per tutta la durata necessaria della conversazione

Limitazioni attuali

Stesso modello per il riepilogo: Il modello specificato nella tua richiesta viene utilizzato per il riepilogo. Non esiste alcuna opzione per utilizzare un modello diverso (ad esempio, più economico) per il riepilogo.
La compattazione potrebbe fallire 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 dica 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

Modifica del contesto

Gestisci automaticamente il contesto della conversazione man mano che cresce con la modifica del contesto.

Finestre di contesto

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

Cookbook sulla compattazione della memoria di sessione

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

Was this page helpful?

MessaggiGestione del contesto

Compattazione

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

Per un approfondimento sul perché i contesti lunghi si degradano e su come la compattazione aiuta, consulta Effective context engineering.

Questo è ideale per:

Conversazioni multi-turno basate su chat in cui desideri che gli utenti utilizzino una singola chat per un lungo periodo di tempo
Prompt orientati ad attività che richiedono molto lavoro di follow-up (spesso uso degli strumenti) che potrebbe superare la finestra di contesto

La compattazione è in beta. Includi il beta header compact-2026-01-12 nelle tue richieste API per utilizzare questa funzionalità.

Modelli supportati

La compattazione è supportata sui seguenti modelli:

Claude Fable 5 (claude-fable-5)
Claude Mythos 5 (claude-mythos-5)
Claude Mythos Preview (claude-mythos-preview)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)

Come funziona la compattazione

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

Rileva quando i token di input raggiungono la soglia di attivazione specificata.
Genera un riepilogo della conversazione corrente.
Crea un blocco compaction contenente il riepilogo.
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 all'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-8",
    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

Parametro	Tipo	Predefinito	Descrizione
`type`	string	Obbligatorio	Deve essere `"compact_20260112"`
`trigger`	object	`{"type": "input_tokens", "value": 150000}`	Quando attivare la compattazione. `input_tokens` è l'unico tipo di trigger supportato. `value` deve essere almeno 50.000 token.
`pause_after_compaction`	boolean	`false`	Se mettere in pausa dopo aver generato il riepilogo di compattazione
`instructions`	string	`null`	Prompt di riepilogo personalizzato. Sostituisce completamente il prompt predefinito quando fornito.

Configurazione del trigger

Configura quando si attiva la compattazione 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-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

Istruzioni di riepilogo personalizzate

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

Applicare un budget totale di token

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-8",
    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 conclusione se oltre 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.

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..."
    }
  ]
}

Passare i blocchi di compattazione all'API

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

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

Mantenere i messaggi originali nella tua lista 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-8",
    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 or '')} chars")
            elif event.delta.type == "text_delta":
                print(event.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 la cache dei prompt. Puoi aggiungere un breakpoint cache_control sui blocchi di compattazione per memorizzare nella cache il contenuto riassunto.

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

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

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    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 mantiene i prompt di sistema lunghi memorizzati nella cache attraverso più eventi di compattazione durante una conversazione.

Comprendere l'utilizzo

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-8",
    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-8",
        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() per tutto il tempo necessario alla conversazione

Ecco un esempio che utilizza pause_after_compaction per preservare lo scambio precedente e il messaggio utente corrente (tre messaggi in totale) alla lettera 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-8",
        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

        # Costruisci la nuova lista di messaggi: compattazione + messaggi conservati
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

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

        # Aggiorna la nostra lista di 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() per tutta la durata necessaria della conversazione

Limitazioni attuali

Stesso modello per il riepilogo: Il modello specificato nella tua richiesta viene utilizzato per il riepilogo. Non esiste alcuna opzione per utilizzare un modello diverso (ad esempio, più economico) per il riepilogo.
La compattazione potrebbe fallire 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 dica 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

Modifica del contesto

Gestisci automaticamente il contesto della conversazione man mano che cresce con la modifica del contesto.

Finestre di contesto

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

Cookbook sulla compattazione della memoria di sessione

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

Was this page helpful?

Modelli supportati

Come funziona la compattazione

Utilizzo di base

Parametri

Configurazione del trigger

Istruzioni di riepilogo personalizzate

Pausa dopo la compattazione

Applicare un budget totale di token

Lavorare con i blocchi di compattazione

Passare i blocchi di compattazione all'API

Streaming

Cache dei prompt

Massimizzare i cache hit con i prompt di sistema

Comprendere l'utilizzo

Combinazione con altre funzionalità

Strumenti server

Conteggio dei token

Esempi

Limitazioni attuali

Passaggi successivi

Modelli supportati

Come funziona la compattazione

Utilizzo di base

Parametri

Configurazione del trigger

Istruzioni di riepilogo personalizzate

Pausa dopo la compattazione

Applicare un budget totale di token

Lavorare con i blocchi di compattazione

Passare i blocchi di compattazione all'API

Streaming

Cache dei prompt

Massimizzare i cache hit con i prompt di sistema

Comprendere l'utilizzo

Combinazione con altre funzionalità

Strumenti server

Conteggio dei token

Esempi

Limitazioni attuali

Passaggi successivi

Modelli supportati

Come funziona la compattazione

Utilizzo di base

Parametri

Configurazione del trigger

Istruzioni di riepilogo personalizzate

Pausa dopo la compattazione

Applicare un budget totale di token

Lavorare con i blocchi di compattazione

Passare i blocchi di compattazione all'API

Streaming

Cache dei prompt

Massimizzare i cache hit con i prompt di sistema

Comprendere l'utilizzo

Combinazione con altre funzionalità

Strumenti server

Conteggio dei token

Esempi

Limitazioni attuali

Passaggi successivi

Modelli supportati

Come funziona la compattazione

Utilizzo di base

Parametri

Configurazione del trigger

Istruzioni di riepilogo personalizzate

Pausa dopo la compattazione

Applicare un budget totale di token

Lavorare con i blocchi di compattazione

Passare i blocchi di compattazione all'API

Streaming

Cache dei prompt

Massimizzare i cache hit con i prompt di sistema

Comprendere l'utilizzo

Combinazione con altre funzionalità

Strumenti server

Conteggio dei token

Esempi

Limitazioni attuali

Passaggi successivi