I nostri SDK Python e TypeScript offrono diversi modi di fare streaming. L’SDK Python consente sia stream sincroni che asincroni. Consulta la documentazione in ogni SDK per i dettagli.
import anthropicclient = anthropic.Anthropic()with client.messages.stream( max_tokens=1024, messages=[{"role":"user","content":"Ciao"}], model="claude-opus-4-1-20250805",)as stream:for text in stream.text_stream:print(text, end="", flush=True)
Ogni evento server-sent include un tipo di evento nominato e dati JSON associati. Ogni evento utilizzerà un nome evento SSE (ad esempio event: message_stop), e includerà il type di evento corrispondente nei suoi dati.
Ogni stream utilizza il seguente flusso di eventi:
message_start: contiene un oggetto Message con content vuoto.
Una serie di blocchi di contenuto, ognuno dei quali ha un content_block_start, uno o più eventi content_block_delta, e un evento content_block_stop. Ogni blocco di contenuto avrà un index che corrisponde al suo indice nell’array content del Messaggio finale.
Uno o più eventi message_delta, che indicano cambiamenti di alto livello all’oggetto Message finale.
Un evento finale message_stop.
I conteggi dei token mostrati nel campo usage dell’evento message_delta sono cumulativi.
Occasionalmente potremmo inviare errori nel flusso di eventi. Ad esempio, durante periodi di alto utilizzo, potresti ricevere un overloaded_error, che normalmente corrisponderebbe a un HTTP 529 in un contesto non-streaming:
In conformità con la nostra politica di versioning, potremmo aggiungere nuovi tipi di eventi, e il tuo codice dovrebbe gestire i tipi di eventi sconosciuti con grazia.
I delta per i blocchi di contenuto tool_use corrispondono agli aggiornamenti per il campo input del blocco. Per supportare la massima granularità, i delta sono stringhe JSON parziali, mentre il tool_use.input finale è sempre un oggetto.
Puoi accumulare i delta delle stringhe e analizzare il JSON una volta ricevuto un evento content_block_stop, utilizzando una libreria come Pydantic per fare il parsing JSON parziale, o utilizzando i nostri SDK, che forniscono helper per accedere ai valori incrementali analizzati.
Un delta del blocco di contenuto tool_use appare così:
Nota: I nostri modelli attuali supportano solo l’emissione di una chiave e valore completi da input alla volta. Pertanto, quando si utilizzano gli strumenti, potrebbero esserci ritardi tra gli eventi di streaming mentre il modello sta lavorando. Una volta che una chiave e valore input sono accumulati, li emettiamo come più eventi content_block_delta con json parziale suddiviso in modo che il formato possa supportare automaticamente una granularità più fine nei modelli futuri.
Quando si utilizza il pensiero esteso con lo streaming abilitato, riceverai il contenuto del pensiero tramite eventi thinking_delta. Questi delta corrispondono al campo thinking dei blocchi di contenuto thinking.
Per il contenuto del pensiero, un evento speciale signature_delta viene inviato appena prima dell’evento content_block_stop. Questa firma viene utilizzata per verificare l’integrità del blocco di pensiero.
Un tipico delta di pensiero appare così:
Delta di pensiero
event: content_block_deltadata:{"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"Risolviamo questo passo dopo passo:\n\n1. Prima scomponiamo 27 * 453"}}
Raccomandiamo vivamente di utilizzare i nostri SDK client quando si utilizza la modalità streaming. Tuttavia, se stai costruendo un’integrazione API diretta, dovrai gestire questi eventi da solo.
Una risposta di stream è composta da:
Un evento message_start
Potenzialmente più blocchi di contenuto, ognuno dei quali contiene:
Un evento content_block_start
Potenzialmente più eventi content_block_delta
Un evento content_block_stop
Un evento message_delta
Un evento message_stop
Potrebbero esserci eventi ping dispersi in tutta la risposta. Vedi Tipi di eventi per maggiori dettagli sul formato.
L’uso degli strumenti ora supporta lo streaming a grana fine per i valori dei parametri come funzionalità beta. Per maggiori dettagli, vedi Streaming fine degli strumenti.
In questa richiesta, chiediamo a Claude di utilizzare uno strumento per dirci il tempo.
curl https://api.anthropic.com/v1/messages \-H"content-type: application/json"\-H"x-api-key: $ANTHROPIC_API_KEY"\-H"anthropic-version: 2023-06-01"\-d '{"model":"claude-opus-4-1-20250805","max_tokens":1024,"tools":[{"name":"get_weather","description":"Ottieni il tempo attuale in una determinata località","input_schema":{"type":"object","properties":{"location":{"type":"string","description":"La città e lo stato, ad es. San Francisco, CA"}},"required":["location"]}}],"tool_choice":{"type":"any"},"messages":[{"role":"user","content":"Com'è il tempo a San Francisco?"}],"stream":true}'
Richiesta di streaming con uso dello strumento di ricerca web
In questa richiesta, chiediamo a Claude di cercare sul web informazioni meteorologiche attuali.
curl https://api.anthropic.com/v1/messages \--header"x-api-key: $ANTHROPIC_API_KEY"\--header"anthropic-version: 2023-06-01"\--header"content-type: application/json"\--data\'{"model":"claude-opus-4-1-20250805","max_tokens":1024,"stream": true,"tools":[{"type":"web_search_20250305","name":"web_search","max_uses":5}],"messages":[{"role":"user","content":"Com'è il tempo a New York City oggi?"}]}'
Risposta
event: message_startdata:{"type":"message_start","message":{"id":"msg_01G...","type":"message","role":"assistant","model":"claude-opus-4-1-20250805","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":2679,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":3}}}event: content_block_startdata:{"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}event: content_block_deltadata:{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Controllerò"}}event: content_block_deltadata:{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" il tempo attuale a New York City per te"}}event: pingdata:{"type":"ping"}event: content_block_deltadata:{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"."}}event: content_block_stopdata:{"type":"content_block_stop","index":0}event: content_block_startdata:{"type":"content_block_start","index":1,"content_block":{"type":"server_tool_use","id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","name":"web_search","input":{}}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"query"}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\":"}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"weather"}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" NY"}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"C to"}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"day\"}"}}event: content_block_stopdata:{"type":"content_block_stop","index":1}event: content_block_startdata:{"type":"content_block_start","index":2,"content_block":{"type":"web_search_tool_result","tool_use_id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","content":[{"type":"web_search_result","title":"Weather in New York City in May 2025 (New York) - detailed Weather Forecast for a month","url":"https://world-weather.info/forecast/usa/new_york/may-2025/","encrypted_content":"Ev0DCioIAxgCIiQ3NmU4ZmI4OC1k...","page_age":null},...]}}event: content_block_stopdata:{"type":"content_block_stop","index":2}event: content_block_startdata:{"type":"content_block_start","index":3,"content_block":{"type":"text","text":""}}event: content_block_deltadata:{"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"Ecco le informazioni meteorologiche attuali per New York"}}event: content_block_deltadata:{"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" City:\n\n# Tempo"}}event: content_block_deltadata:{"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" a New York City"}}event: content_block_deltadata:{"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"\n\n"}}...event: content_block_stopdata:{"type":"content_block_stop","index":17}event: message_deltadata:{"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":10682,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":510,"server_tool_use":{"web_search_requests":1}}}event: message_stopdata:{"type":"message_stop"}
Quando una richiesta di streaming viene interrotta a causa di problemi di rete, timeout o altri errori, puoi recuperare riprendendo da dove il flusso è stato interrotto. Questo approccio ti fa risparmiare dal dover riprocessare l’intera risposta.
La strategia di recupero di base comporta:
Catturare la risposta parziale: Salvare tutto il contenuto che è stato ricevuto con successo prima che si verificasse l’errore
Costruire una richiesta di continuazione: Creare una nuova richiesta API che includa la risposta parziale dell’assistente come inizio di un nuovo messaggio dell’assistente
Riprendere lo streaming: Continuare a ricevere il resto della risposta da dove è stata interrotta
Utilizzare le funzionalità dell’SDK: Sfruttare le capacità integrate dell’SDK per l’accumulo dei messaggi e la gestione degli errori
Gestire i tipi di contenuto: Essere consapevoli che i messaggi possono contenere più blocchi di contenuto (text, tool_use, thinking). I blocchi di uso degli strumenti e di pensiero esteso non possono essere recuperati parzialmente. Puoi riprendere lo streaming dal blocco di testo più recente.
