Compattazione su richiesta

Con la "on-demand compaction" (compattazione su richiesta), è la tua applicazione a decidere quando una conversazione viene riassunta: invii una richiesta con il parametro compaction e Claude restituisce un riepilogo al posto di una risposta.

Come funziona la compattazione su richiesta

Una richiesta di compattazione è separata dai turni della tua conversazione. Invii la conversazione così com'è con il parametro compaction, e la risposta contiene un singolo blocco compaction. Il blocco contiene il riepilogo sotto forma di testo leggibile e una firma. Invialo nelle richieste successive esattamente come è arrivato.

Da quel momento in poi il blocco prende il posto dei messaggi che riassume. Va per primo in messages, i messaggi riassunti vengono rimossi e il tuo turno successivo lo segue. Claude vede il riepilogo dove si trovavano quei messaggi.

Richiedi un riepilogo

Invia l'header beta compact-2026-09-04 nella richiesta che chiede il riepilogo e in ogni richiesta successiva che contiene il blocco firmato. Per verificare se un modello supporta la compattazione su richiesta, chiama la Models API con l'header beta e leggi capabilities.compaction di ciascun modello. Non puoi combinare compaction con context_management in una stessa richiesta.

Invia la conversazione così com'è con "compaction": {"type": "summarize"}. L'API riassume una sola volta tutti i messaggi della richiesta, non genera alcuna risposta dopo di essi e restituisce solo il blocco con stop_reason "compaction". Invia lo stesso prompt system e gli stessi tools che usi per il resto della conversazione. Il processo di riepilogo li legge e, se mantieni dei turni dopo il blocco su un modello con "preserved thinking" (ragionamento preservato), il ragionamento in quei turni resta valido solo se system e tools corrispondono. La conversazione in questo esempio non ha né un prompt system né strumenti, quindi la richiesta non invia nessuno dei due:

from anthropic.types.beta import BetaMessageParam

client = anthropic.Anthropic()

history: list[BetaMessageParam] = [
    {
        "role": "user",
        "content": "I am building a recipe app. Help me name the main entities in the data model.",
    },
    {
        "role": "assistant",
        "content": "Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe.",
    },
    {"role": "user", "content": "Good. Now suggest field names for Recipe."},
]

response = client.beta.messages.create(
    model="claude-opus-5-5",
    # max_tokens limita l'intera chiamata, incluso l'eventuale ragionamento, quindi prevedi diverse migliaia di token.
    max_tokens=4096,
    betas=["compact-2026-09-04"],
    messages=history,
    compaction={"type": "summarize"},
)
print(f"Stop reason: {response.stop_reason}")

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: the user is designing the data model for a recipe app. The entities agreed so far are Recipe, Ingredient, Step, and RecipeIngredient, which holds the quantity and unit. The user then asked for field names for Recipe.",
      "signature": "EuYBCkQY..."
    }
  ],
  "stop_reason": "compaction",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "iterations": [{ "type": "compaction", "input_tokens": 144, "output_tokens": 276 }]
  }
}

La chiamata di riepilogo usa il modello, system, tools, le impostazioni di ragionamento e max_tokens della richiesta. Il processo di riepilogo legge le definizioni degli strumenti ma non esegue mai uno strumento, e la risposta non contiene alcun ragionamento. max_tokens limita l'intera chiamata, incluso qualsiasi ragionamento che il modello svolge prima di scrivere il riepilogo, quindi prevedi diverse migliaia di token. Conteggia l'utilizzo della compattazione mostra come viene fatturata la chiamata.

Se l'ultimo turno assistant termina con una chiamata a uno strumento ancora priva di risultato, l'API rifiuta la richiesta. Invia prima i risultati degli strumenti di quel turno. Ometti inoltre stop_sequences, output_config.format per l'output strutturato e un tool_choice di tipo any o tool. Non avrebbero alcun effetto in una chiamata di riepilogo, e l'API li rifiuta. La conversazione deve comunque rientrare nella "context window" (finestra di contesto) del modello, quindi compatta prima di superarla, non dopo.

Quando esegui lo streaming della risposta, il blocco arriva intero. Ricevi un evento content_block_start che contiene il blocco completo, poi content_block_stop, senza eventi content_block_delta. Gli eventi ping possono arrivare prima o tra di essi.

Continua dal riepilogo

Nella tua cronologia, sostituisci i messaggi che hai inviato con il messaggio assistant restituito. Mantieni il blocco compaction esattamente come l'API lo ha restituito, inclusa la sua signature. Eventuali turni svolti dopo l'invio della richiesta di compattazione seguono il blocco invariati, ed è su questo che si basa Compattazione in background. Invia il blocco per primo in ogni richiesta successiva, con l'header beta:

{
  "model": "claude-opus-5-5",
  "max_tokens": 2048,
  "messages": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "compaction",
          "content": "Summary of the conversation: the user is designing the data model for a recipe app. The entities agreed so far are Recipe, Ingredient, Step, and RecipeIngredient, which holds the quantity and unit. The user then asked for field names for Recipe.",
          "signature": "EuYBCkQY..."
        }
      ]
    },
    {
      "role": "assistant",
      "content": "For Recipe, use title, description, servings, prep_minutes, and cook_minutes. Add created_at and updated_at timestamps."
    },
    { "role": "user", "content": "Now do the same for Ingredient." }
  ]
}

Questo esempio prosegue l'esempio di richiesta, che terminava con un turno user; il diagramma mostra il caso più semplice, in cui nessun turno viene svolto mentre il riepilogo viene scritto. Qui il secondo messaggio assistant è la risposta all'ultimo turno user riassunto. È arrivato mentre il riepilogo veniva scritto, quindi non era tra i messaggi riassunti. Due messaggi assistant consecutivi vanno bene in questo caso, perché il blocco viene comunque per primo.

L'API colloca il riepilogo dove si trova il blocco e passa a Claude invariati tutti i messaggi successivi. Segui queste regole:

• Metti il blocco per primo in messages, come messaggio assistant a sé stante oppure come primo blocco di contenuto del primo messaggio, che si tratti di un messaggio user o assistant.
• Rimuovi i messaggi riassunti. Se ne rimane qualcuno davanti al blocco, la richiesta restituisce un errore 400 (compaction_block_misplaced).
• Invia esattamente un blocco compaction per richiesta, in ogni richiesta successiva.

La "threshold compaction" (compattazione a soglia) funziona al contrario: il suo blocco segue i messaggi che riassume, e l'API li elimina per te. Consulta Restituire i blocchi di compattazione.

In Python, usa client.beta.messages, come fanno gli esempi in questa pagina. Se chiami client.messages e serializzi i blocchi da solo, usa to_dict() o model_dump(exclude_none=True): un semplice model_dump() aggiunge citations: null e text: null al blocco, e l'API lo rifiuta.

Se mantieni dei turni dopo il blocco e rinvii i relativi blocchi di ragionamento, le condizioni che mantengono valido quel ragionamento sono descritte in Compattazione e ragionamento preservato.

Compatta di nuovo

Per compattare una conversazione che inizia già con un blocco, invia di nuovo compaction. Il nuovo blocco riassume il vecchio riepilogo e tutto ciò che lo segue. Da quel momento in poi, invia solo il blocco più recente.

Compatta in un ciclo

Dopo ogni turno, il ciclo somma i token di input e di output dell'ultima risposta, perché la richiesta successiva invia anche la risposta. Quando quel totale supera un limite e deve ancora seguire un altro turno, il ciclo invia una richiesta di compattazione con lo stesso modello e lo stesso prompt system, controlla stop_reason, sostituisce la propria cronologia con il messaggio restituito e stampa il turno prima del quale ha compattato. Il limite di 2.500 token dell'esempio è volutamente basso, in modo che anche una conversazione breve venga compattata. Imposta il tuo limite vicino al tuo budget di input reale.

from anthropic.types.beta import BetaMessageParam