Message threads nell'API di Claude: si inviano solo i messaggi nuovi

Anthropic ha rilasciato in beta i message threads dell’API di Claude: la conversazione resta per poco sul server e ogni richiesta successiva invia solo i messaggi nuovi. La novità è comparsa nelle Claude Release Notes il 2 novembre e funziona con l’header beta message-threads-2026-08-12.

Come funzionano i message threads nell’API di Claude?

Finora ogni turno di una conversazione con la Messages API significava inviare di nuovo l’intera cronologia: prompt di sistema, strumenti e tutti i messaggi. Secondo la documentazione dei message threads, l’API doveva ogni volta rivalidare e ritokenizzare tutto. Con un thread, gran parte di questo lavoro riguarda solo il turno nuovo.

L’intero meccanismo è un nuovo parametro, thread:

1. La prima richiesta si invia come sempre, con la conversazione completa, system e tools, più "thread": {"type": "create"}. L’API salva la conversazione insieme alla risposta di Claude sotto l’id di quella risposta.
2. Le richieste successive contengono "thread": {"type": "continue", "previous_message_id": "<id>"} e solo i messaggi nuovi, ad esempio il messaggio successivo dell’utente o i risultati degli strumenti (tool_result).
3. system e tools si omettono, perché il thread li ricorda. Inviarli in una richiesta continue restituisce un errore 400.

Secondo Anthropic il risultato sono richieste più piccole e un tempo al primo token più breve e stabile, anche quando la conversazione si allunga. Ci guadagnano soprattutto i lunghi loop degli agenti, in cui l’agente fa decine di chiamate agli strumenti e ogni volta doveva rimandare una cronologia sempre più lunga (per capire come funzionano questi loop, vedi l’articolo cos’è un agente AI).

Cosa fa l’SDK al posto nostro?

L’SDK ha un nuovo helper, client.beta.messages.thread(...). Lo si crea con gli stessi campi di una richiesta normale, poi si inviano i turni successivi con thread.send(...). L’helper aggiunge da solo l’header beta, crea il thread al primo turno e lo prosegue in quelli seguenti.

Curiosamente, il tool runner beta dell’SDK usa i thread di default, quindi gli agenti costruiti su di esso possono diventare più veloci senza modificare il codice (si può disattivare quando si crea il runner).

L’helper gestisce anche i casi di errore: quando un thread scade, rimanda l’intera conversazione in una nuova richiesta create. La copia completa, però, la tiene solo in memoria, finché esiste l’oggetto helper.

A cosa fare attenzione?

Primo, alla vita breve. Un thread scade 5 minuti dopo l’ultima richiesta e l’API lo cancella al massimo un’ora dopo l’ultimo utilizzo. La documentazione definisce i thread „best-effort”: la nostra applicazione deve restare la fonte di verità della conversazione e gestire fin dall’inizio il reinvio completo dopo un errore 404 thread_not_found.

Secondo, a ciò che non si può cambiare. Campi come model, thinking, tool_choice o context_management devono avere gli stessi valori per tutto il thread, altrimenti l’API restituisce l’errore thread_fingerprint_mismatch. Un thread può solo allungarsi e ogni id di risposta si può proseguire una sola volta. Per modificare un messaggio precedente o cambiare il prompt di sistema si avvia un nuovo thread.

Terzo, al prompt caching. Un thread da solo non mette nulla in cache. La cache funziona come prima, e una richiesta con thread ammette al massimo 4 punti cache_control. La cosa più semplice è inviare a ogni turno lo stesso cache_control al livello più alto della richiesta.

Quarto, alle funzionalità con cui i thread non funzionano:

1. Message Batches e Token Counting.
2. Compaction, compresa la compattazione su richiesta, e il context editing (con un’eccezione descritta nella documentazione).
3. Le organizzazioni con HIPAA readiness o Inference hooks attivi.

Quinto, ai dati. I thread non sono idonei allo ZDR (zero data retention). Secondo la documentazione, la conversazione, il prompt di sistema e gli strumenti restano in memoria, cifrati con una chiave gestita dal server, e non vengono mai scritti su disco persistente.

Dove e con quali modelli funziona?

I message threads sono in beta sull’API di Claude, su Claude Platform on AWS, Claude Models on Google Cloud (gestiti da Anthropic) e Microsoft Foundry. Tra i modelli supportati ci sono Claude Fable 5.1 e Mythos 5.1, Opus 5.5, Sonnet 5.5 e Haiku 5.5, e tra i più vecchi anche Opus 4.5, Sonnet 4.5 e Haiku 4.5.

I thread non cambiano prezzi né limiti di richieste. I token si pagano come prima, quindi il risparmio riguarda tempo e dimensione delle richieste, e conviene continuare a monitorare i costi, ad esempio con la nuova API di analisi dei costi di Claude. È un altro cambiamento nell’API stessa degli ultimi giorni, dopo l’aumento del limite di richiesta a 128 MB.

(Da non confondere con i „session threads” di Claude Managed Agents. È una funzionalità separata, come ricorda la documentazione.)

FAQ

Cosa sono i message threads dell’API di Claude?

Una funzionalità beta in cui l’API conserva per poco tempo la conversazione sul server. Dopo la prima richiesta si inviano solo i messaggi nuovi e l’id della risposta precedente.

I message threads riducono i costi dell’API di Claude?

Non direttamente. Secondo la documentazione, i thread non cambiano prezzi né limiti di richieste. Il vantaggio sono richieste più piccole e un tempo al primo token più breve.

Per quanto tempo l’API di Claude conserva un thread?

Un thread scade 5 minuti dopo l’ultima richiesta e l’API lo cancella al massimo un’ora dopo l’ultimo utilizzo. Dopo bisogna rimandare l’intera conversazione.

I message threads funzionano su Amazon Bedrock?

La documentazione elenca l’API di Claude, Claude Platform on AWS, Claude Models on Google Cloud (gestiti da Anthropic) e Microsoft Foundry. Amazon Bedrock non compare nell’elenco.