--- title: Visualizzare in anteprima le risposte con i delta degli eventi url: https://platform.claude.com/docs/it/managed-agents/event-deltas description: Visualizza il testo della risposta dell'agente come anteprima in tempo reale mentre il modello lo sta ancora generando. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Per impostazione predefinita, il testo della risposta dell'agente raggiunge il [flusso di eventi della sessione](https://platform.claude.com/docs/it/managed-agents/events-and-streaming) come eventi `agent.message` bufferizzati. Ciascuno viene emesso solo dopo che la richiesta al modello che lo ha prodotto è terminata. Gli "event deltas" (delta degli eventi) ti consentono di visualizzare quel testo in modo incrementale, come anteprima in tempo reale, mentre il modello lo sta ancora generando. Le anteprime sono un ausilio di visualizzazione fornito secondo il principio del "best effort" (massimo impegno), e l'`agent.message` bufferizzato è sempre il record autorevole. Un client che ignora le anteprime riceve comunque un flusso completo e corretto. ## Attivare le anteprime Le anteprime sono facoltative e si attivano per singola connessione di flusso. Aggiungi il parametro di query `event_deltas[]` al flusso che stai leggendo e ripetilo una volta per ogni tipo di evento di cui desideri l'anteprima. I valori accettati sono `agent.message` e `agent.thinking`. Qualsiasi altro valore restituisce un errore 400, così come una richiesta con più di 100 valori. Entrambi gli endpoint di flusso accettano il parametro: * **Flusso a livello di sessione:** `GET /v1/sessions/{session_id}/events/stream` * **Flusso del thread di sessione:** `GET /v1/sessions/{session_id}/threads/{thread_id}/stream` Le anteprime di un subagente compaiono sul [flusso del thread di quel subagente](https://platform.claude.com/docs/it/managed-agents/event-deltas#preview-session-thread-events). `[]` è un pattern glob della shell, quindi racchiudi l'URL tra virgolette ogni volta che costruisci la richiesta in una shell. Gli esempi codificano le parentesi quadre in percent-encoding come `%5B%5D`, che funziona ugualmente. ### Eventi di anteprima Quando inizia un evento in anteprima, il flusso emette un `event_start` che riporta il tipo e l'`id` dell'evento in arrivo: ```json { "type": "event_start", "event": { "type": "agent.message", "id": "sevt_01abc..." } } ``` Per `agent.message`, l'inizio è seguito da eventi `event_delta` che trasportano testo incrementale. Ogni delta indica l'evento che estende in `event_id` e il blocco di contenuto che estende in `delta.index`: ```json { "type": "event_delta", "event_id": "sevt_01abc...", "delta": { "type": "content_delta", "index": 0, "content": { "type": "text", "text": "Here is the summary" } } } ``` Per `agent.thinking`, viene emesso solo l'`event_start`, come segnale che un blocco di ragionamento è iniziato. Non seguono eventi `event_delta`. L'evento `agent.thinking` bufferizzato che conclude l'anteprima è un segnale di avanzamento e non contiene alcun contenuto di ragionamento. A differenza degli eventi persistiti, `event_start` e `event_delta` non hanno un proprio `id` o `processed_at`. L'unico identificatore che trasportano è l'`id` dell'evento di cui forniscono l'anteprima. Le loro stringhe di tipo costituiscono inoltre l'eccezione alla convenzione di denominazione `{domain}.{action}` degli eventi persistiti. I delta degli eventi usano un formato di trasmissione diverso da quello dello [Streaming dei messaggi](https://platform.claude.com/docs/it/build-with-claude/streaming), e la differenza è intenzionale. Un `agent.message` in anteprima riceve un singolo `event_start` seguito solo da eventi `event_delta`. Non ci sono eventi di inizio o fine per singolo blocco di contenuto né un evento di fine per l'evento in anteprima stesso. Il tipo di delta è `content_delta`, non `content_block_delta`. Il codice di accumulo scritto per la Messages API non è riutilizzabile senza modifiche. ## Accumulare e riconciliare Ogni SDK che supporta i delta degli eventi include un [helper di accumulo](https://platform.claude.com/docs/it/managed-agents/event-deltas#sdk-accumulator-helpers) che gestisce per te la contabilità dell'`index`. Il pattern manuale descritto in questa sezione funziona in ogni linguaggio quando hai bisogno di una gestione personalizzata. Applicalo ai tipi di evento generati. Nel pattern manuale, conserva il testo dell'anteprima in una mappa temporanea con chiave `(event_id, index)` e tratta l'evento bufferizzato come il record. Riconcilia i due per ogni richiesta al modello. Un turno si apre con un singolo evento `session.status_running`. In un turno che si completa normalmente, ogni richiesta al modello produce quindi questi eventi, in ordine: 1. `span.model_request_start` 2. `event_start` 3. Gli eventi `event_delta` 4. L'`agent.message` bufferizzato 5. [`span.model_request_end`](https://platform.claude.com/docs/it/managed-agents/reference#event-types) (nella scheda Span events) Sul canale di trasmissione, questa è la parte in anteprima di quella sequenza, intercalata con gli altri eventi bufferizzati della connessione: ```text wrap event_start {"event": {"type": "agent.message", "id": "sevt_01abc..."}} event_delta {"event_id": "sevt_01abc...", "delta": {"type": "content_delta", "index": 0, "content": {"type": "text", "text": "..."}}} ... agent.message {"id": "sevt_01abc...", "content": [...]} ``` La riga `event_delta` si ripete una volta per ogni frammento di testo. Elabora ogni evento man mano che arriva: 1. Su `event_start`, annota l'`id` annunciato. Gli identificatori corrispondono sempre: `event_start.event.id`, ogni `event_delta.event_id` e l'`id` dell'`agent.message` bufferizzato hanno lo stesso valore. 2. Su ogni `event_delta`, aggiungi `delta.content.text` alla voce in `(event_id, delta.index)` e visualizza il testo parziale. Il primo delta per un `index` crea quella voce. 3. Quando arriva l'`agent.message` bufferizzato, associalo tramite `id`, scarta l'anteprima accumulata e visualizza invece il contenuto del messaggio. 4. Su `span.model_request_end`, chiudi qualsiasi anteprima che non sia stata riconciliata dal relativo evento bufferizzato. Non arriveranno altri delta per essa. Se il turno genera un errore o viene interrotto, l'evento bufferizzato potrebbe non arrivare mai, ma `span.model_request_end` arriva comunque. Il pattern si basa su due garanzie: * Concatenando i delta di un'anteprima nell'ordine di arrivo, con chiave `(event_id, index)`, si ottiene un prefisso di `content[index].text` nell'evento bufferizzato. Non è necessariamente il testo completo, perché i delta potrebbero essere [scartati sotto carico](https://platform.claude.com/docs/it/managed-agents/event-deltas#limitations). * Una connessione emette al massimo un `event_start` per `event_id`, e l'evento bufferizzato è l'ultima cosa che quella connessione consegna per quell'`id`. ### Helper di accumulo degli SDK L'helper di ciascun SDK gestisce la contabilità dell'`index` (csharp, go: `Index`). Gli helper Go, Java, Ruby e C# usano inoltre come chiave dell'anteprima in accumulo l'`id` (csharp, go: `ID`) dell'evento. Con gli helper Python, TypeScript e PHP, mantieni tu stesso quella mappa e integra ogni delta nella voce corrispondente al suo `id` (csharp, go: `ID`). Gli esempi seguenti attivano le anteprime di `agent.message` e le riconciliano con l'evento bufferizzato: Questo flusso di lavoro richiede più logica di un singolo comando shell. Usa il [Claude SDK](https://platform.claude.com/docs/it/cli-sdks-libraries/overview) per eseguirlo. Questo flusso di lavoro richiede più logica di un singolo comando shell. Usa il [Claude SDK](https://platform.claude.com/docs/it/cli-sdks-libraries/overview) per eseguirlo. ```python Python # Snapshot di anteprima, indicizzati per id evento. accumulate_managed_agents_event integra ogni # event_start / event_delta in uno snapshot agent.message; l'agent.message # nel buffer lo sostituisce. previews: dict[str, BetaManagedAgentsAgentMessageEvent] = {} # Abilita le anteprime di agent.message su questa connessione with client.beta.sessions.events.stream( session.id, event_deltas=["agent.message"] ) as stream: client.beta.sessions.events.send( session.id, events=[ { "type": "user.message", "content": [ {"type": "text", "text": "Describe the repo in one sentence."} ], }, ], ) for event in stream: match event.type: case "event_start": snapshot = accumulate_managed_agents_event(None, event) if snapshot is not None: previews[event.event.id] = snapshot print(f"event_start {event.event.type} {event.event.id}") case "event_delta": preview = accumulate_managed_agents_event( previews.get(event.event_id), event ) if preview is not None: previews[event.event_id] = preview text = "".join(block.text for block in preview.content) print(f"event_delta preview: {text!r}") case "agent.message": # L'evento nel buffer è il record: sostituisce e chiude l'anteprima preview = accumulate_managed_agents_event( previews.pop(event.id, None), event ) text = "".join(block.text for block in preview.content) print(f"agent.message {event.id} {text!r}") case "span.model_request_end": # Non arriveranno altri delta. Chiudi ogni anteprima il cui # evento nel buffer non è mai arrivato. for event_id in previews: print(f"span.model_request_end closing preview for {event_id}") previews.clear() case "session.status_idle": break ``` ```typescript TypeScript // Snapshot di anteprima, indicizzati per id evento. `accumulateManagedAgentsEvent` // unisce le anteprime event_start / event_delta in uno snapshot agent.message. const previews = new Map(); // Abilita le anteprime agent.message solo per questa connessione const stream = await client.beta.sessions.events.stream(session.id, { event_deltas: ["agent.message"] }); await client.beta.sessions.events.send(session.id, { events: [ { type: "user.message", content: [{ type: "text", text: "Summarize the repo README" }] } ] }); deltas: for await (const event of stream) { switch (event.type) { case "event_start": { // 1. Annota l'id annunciato e apri lo snapshot. I delta e l'evento // bufferizzato hanno lo stesso id. const preview = accumulateManagedAgentsEvent(undefined, event); if (preview) { previews.set(event.event.id, preview); } console.log(`event_start ${event.event.type} ${event.event.id}`); break; } case "event_delta": { // 2. Unisci il frammento nello snapshot e visualizzalo const preview = accumulateManagedAgentsEvent(previews.get(event.event_id), event); if (preview) { previews.set(event.event_id, preview); const text = preview.content .map((block) => (block.type === "text" ? block.text : "")) .join(""); console.log(`event_delta preview: ${JSON.stringify(text)}`); } break; } case "agent.message": { // 3. L'evento bufferizzato è il record: sostituisce e chiude l'anteprima const message = accumulateManagedAgentsEvent(previews.get(event.id), event); previews.delete(event.id); const text = message.content .map((block) => (block.type === "text" ? block.text : "")) .join(""); console.log(`agent.message ${event.id} ${JSON.stringify(text)}`); break; } case "span.model_request_end": // 4. Non arriveranno altri delta. Chiudi ogni anteprima mai riconciliata. for (const eventId of previews.keys()) { console.log(`span.model_request_end closing preview for ${eventId}`); } previews.clear(); break; case "session.status_idle": break deltas; } } stream.controller.abort(); ``` ```csharp C# // Attiva i delta degli eventi: gli eventi agent.message vengono mostrati in anteprima mentre sono prodotti. using var stream = await client.Beta.Sessions.Events.WithRawResponse.StreamStreaming( session.ID, new() { EventDeltas = [BetaManagedAgentsDeltaType.AgentMessage] } ); await client.Beta.Sessions.Events.Send(session.ID, new() { Events = [ new BetaManagedAgentsUserMessageEventParams { Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage, Content = [ new BetaManagedAgentsTextBlock { Type = BetaManagedAgentsTextBlockType.Text, Text = "Write a haiku about event streams.", }, ], }, ], }); // Accumula i frammenti di anteprima per (id evento, indice contenuto). L'evento // agent.message bufferizzato che segue contiene il contenuto completo, quindi sostituisce // l'anteprima accumulata invece di aggiungersi a essa. Dictionary> previews = []; await foreach (var streamEvent in stream.Enumerate()) { if (streamEvent.TryPickStartEvent(out var start)) { // Un'anteprima aperta per l'evento con questo id. Questo stream attiva solo // i delta di agent.message; TryPick* restituisce false invece di lanciare eccezioni, // quindi gli altri tipi di anteprima (inclusi quelli aggiunti in futuro) vengono saltati. if (start.Event.TryPickAgentMessage(out var preview)) { Console.WriteLine($"event_start {preview.Type.Raw()} {preview.ID}"); } } else if (streamEvent.TryPickDeltaEvent(out var delta)) { // Inserisci a un nuovo indice, accoda a uno esistente if (!previews.TryGetValue(delta.EventID, out var fragments)) { previews[delta.EventID] = fragments = []; } var index = delta.Delta.Index ?? 0; fragments[index] = fragments.GetValueOrDefault(index, "") + delta.Delta.Content.Text; Console.WriteLine($"event_delta preview: {fragments[index]}"); } else if (streamEvent.TryPickAgentMessageEvent(out var message)) { // I delta sono best-effort: scarta l'anteprima e usa l'evento bufferizzato previews.Remove(message.ID); var text = string.Concat(message.Content.Select(block => block.TryPickBetaManagedAgentsTextBlock(out var textBlock) ? textBlock.Text : "")); Console.WriteLine($"agent.message {message.ID} {text}"); } else if (streamEvent.TryPickSpanModelRequestEndEvent(out _)) { // Non arriveranno altri delta; chiudi ogni anteprima mai riconciliata. foreach (var eventId in previews.Keys) { Console.WriteLine($"span.model_request_end closing preview for {eventId}"); } previews.Clear(); } else if (streamEvent.TryPickSessionStatusIdleEvent(out _)) { break; } } ``` ```go Go // Abilita le anteprime incrementali degli eventi agent.message stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{ EventDeltas: []anthropic.BetaManagedAgentsDeltaType{ anthropic.BetaManagedAgentsDeltaTypeAgentMessage, }, }) if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{ Events: []anthropic.BetaManagedAgentsEventParamsUnion{{ OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{ OfText: &anthropic.BetaManagedAgentsTextBlockParam{ Type: anthropic.BetaManagedAgentsTextBlockTypeText, Text: "Write a haiku about the ocean.", }, }}, }, }}, }); err != nil { panic(err) } // L'accumulatore combina i frammenti event_start / event_delta in // snapshot agent.message per ID evento. Il valore zero è pronto all'uso. var previews anthropic.BetaManagedAgentsEventAccumulator deltas: for stream.Next() { event := stream.Current() previews.Accumulate(event) switch event := event.AsAny().(type) { case anthropic.BetaManagedAgentsStartEvent: fmt.Printf("event_start %s %s\n", event.Event.Type, event.Event.ID) case anthropic.BetaManagedAgentsDeltaEvent: fmt.Printf("event_delta preview: %q\n", previews.AgentMessageText(event.EventID)) case anthropic.BetaManagedAgentsAgentMessageEvent: // L'evento bufferizzato contiene il contenuto completo: l'accumulatore // sostituisce l'anteprima con esso fmt.Printf("agent.message %s %q\n", event.ID, previews.AgentMessageText(event.ID)) case anthropic.BetaManagedAgentsSpanModelRequestEndEvent: // Non arriveranno altri delta per questa richiesta. L'accumulatore // scarta qui i suoi snapshot, chiudendo ogni anteprima mai // riconciliata da un agent.message bufferizzato. fmt.Println("span.model_request_end no more deltas for this request") case anthropic.BetaManagedAgentsSessionStatusIdleEvent: break deltas } } if err := stream.Err(); err != nil { panic(err) } stream.Close() ``` ```java Java // Testo di anteprima, indicizzato per ID evento e poi indice del contenuto. L'agent.message bufferizzato lo sostituisce. Map> previews = new HashMap<>(); // Abilita le anteprime di agent.message su questa connessione try (var stream = client.beta().sessions().events().streamStreaming( session.id(), EventStreamParams.builder() .addEventDelta(BetaManagedAgentsDeltaType.AGENT_MESSAGE) .build() )) { client.beta().sessions().events().send( session.id(), EventSendParams.builder() .addEvent(BetaManagedAgentsUserMessageEventParams.builder() .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE) .addTextContent("Describe the repo in one sentence.") .build()) .build() ); Iterable events = stream.stream()::iterator; deltas: for (var event : events) { switch (event.type().value()) { case EVENT_START -> { if (event.asEventStart().event().isAgentMessage()) { var preview = event.asEventStart().event().asAgentMessage(); IO.println("event_start " + preview.type().asString() + " " + preview.id()); } } case EVENT_DELTA -> { var eventDelta = event.asEventDelta(); var fragment = eventDelta.delta(); var buffer = previews .computeIfAbsent(eventDelta.eventId(), _ -> new HashMap<>()) .computeIfAbsent(fragment.index().orElse(0L), _ -> new StringBuilder()); buffer.append(fragment.content().text()); IO.println("event_delta preview: " + buffer); } case AGENT_MESSAGE -> { // L'evento bufferizzato è il record: scarta la sua anteprima, renderizza il suo contenuto var message = event.asAgentMessage(); previews.remove(message.id()); var text = message.content().stream() .flatMap(block -> block.text().stream()) .map(textBlock -> textBlock.text()) .collect(Collectors.joining()); IO.println("agent.message " + message.id() + " " + text); } case SPAN_MODEL_REQUEST_END -> { // Non arriveranno altri delta. Chiudi ogni anteprima il cui evento bufferizzato non è mai arrivato. previews.keySet().forEach(eventId -> IO.println("span.model_request_end closing preview for " + eventId)); previews.clear(); } case SESSION_STATUS_IDLE -> { break deltas; } } } } ``` ```php PHP use Anthropic\Beta\Sessions\BetaManagedAgentsDeltaEvent; use Anthropic\Beta\Sessions\BetaManagedAgentsDeltaType; use Anthropic\Beta\Sessions\BetaManagedAgentsStartEvent; use Anthropic\Beta\Sessions\Events\ManagedAgentsAgentMessageEvent; use Anthropic\Beta\Sessions\Events\ManagedAgentsSessionStatusIdleEvent; use Anthropic\Beta\Sessions\Events\ManagedAgentsSpanModelRequestEndEvent; use Anthropic\Beta\Sessions\Events\ManagedAgentsTextBlock; use Anthropic\Lib\Sessions\EventAccumulator; // Snapshot di anteprima, indicizzati per id evento. EventAccumulator::accumulate() aggiunge ogni // event_start / event_delta a uno snapshot agent.message; l'agent.message // nel buffer lo sostituisce. $previews = []; // Il testo di uno snapshot o evento agent.message $textOf = fn (ManagedAgentsAgentMessageEvent $message): string => implode( '', array_map( fn ($block) => $block->text, array_filter( $message->content, fn ($block) => $block instanceof ManagedAgentsTextBlock, ), ), ); // Abilita le anteprime agent.message su questa connessione $stream = $client->beta->sessions->events->streamStream( $session->id, eventDeltas: [BetaManagedAgentsDeltaType::AGENT_MESSAGE], ); $client->beta->sessions->events->send( $session->id, events: [ [ 'type' => 'user.message', 'content' => [['type' => 'text', 'text' => 'Describe the repo in one sentence.']], ], ], ); foreach ($stream as $event) { switch (true) { case $event instanceof BetaManagedAgentsStartEvent: $snapshot = EventAccumulator::accumulate(null, $event); if ($snapshot !== null) { $previews[$event->event->id] = $snapshot; } printf("event_start %s %s\n", $event->event->type, $event->event->id); break; case $event instanceof BetaManagedAgentsDeltaEvent: // Salta un delta tardivo per un'anteprima già sostituita o chiusa if (!isset($previews[$event->eventID])) { break; // Break switch statement } $previews[$event->eventID] = EventAccumulator::accumulate($previews[$event->eventID], $event); printf("event_delta preview: %s\n", json_encode($textOf($previews[$event->eventID]))); break; case $event instanceof ManagedAgentsAgentMessageEvent: // L'evento nel buffer è il record: sostituisce e chiude l'anteprima unset($previews[$event->id]); printf("agent.message %s %s\n", $event->id, json_encode($textOf($event))); break; case $event instanceof ManagedAgentsSpanModelRequestEndEvent: // Non arriveranno altri delta. Chiudi ogni anteprima il cui // evento nel buffer non è mai arrivato. foreach (array_keys($previews) as $eventID) { printf("span.model_request_end closing preview for %s\n", $eventID); } $previews = []; break; case $event instanceof ManagedAgentsSessionStatusIdleEvent: break 2; // Break foreach loop } } $stream->close(); ``` ```ruby Ruby # Attiva i delta degli eventi: le anteprime di agent.message arrivano come frammenti incrementali. stream = client.beta.sessions.events.stream_events( session.id, event_deltas: [Anthropic::Beta::BetaManagedAgentsDeltaType::AGENT_MESSAGE] ) client.beta.sessions.events.send_( session.id, events: [{ type: "user.message", content: [{type: "text", text: "Give a one-sentence project tagline."}] }] ) # Accumula i frammenti di anteprima per (event_id, index) in buffer esplicitamente mutabili # (`+""`) così `<<` può aggiungere sul posto. L'agent.message bufferizzato con # lo stesso id è autorevole e sostituisce quanto costruito dai delta. buffers = Hash.new do |by_event, event_id| by_event[event_id] = Hash.new { |fragments, index| fragments[index] = +"" } end stream.each do |event| case event when Anthropic::Beta::BetaManagedAgentsStartEvent puts "event_start #{event.event.type} #{event.event.id}" when Anthropic::Beta::BetaManagedAgentsDeltaEvent delta = event.delta fragment = delta.content.text buffers[event.event_id][delta.index || 0] << fragment puts "event_delta preview: #{buffers[event.event_id][delta.index || 0].inspect}" when Anthropic::Beta::Sessions::BetaManagedAgentsAgentMessageEvent # Sostituisci: scarta l'anteprima accumulata e mostra l'evento completo. buffers.delete(event.id) puts "agent.message #{event.id} #{event.content.map(&:text).join.inspect}" when Anthropic::Beta::Sessions::BetaManagedAgentsSpanModelRequestEndEvent # Non arriveranno altri delta. Chiudi ogni anteprima mai riconciliata. buffers.each_key { |event_id| puts "span.model_request_end closing preview for #{event_id}" } buffers.clear when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusIdleEvent break else # ignora gli altri tipi di evento end end ``` ## Visualizzare in anteprima gli eventi dei thread di sessione In una sessione [multiagente](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration), ogni thread di sessione ha il proprio flusso di eventi. Accetta lo stesso parametro `event_deltas[]` con gli stessi valori. Una connessione fornisce l'anteprima solo del thread che sta leggendo. Il flusso a livello di sessione fornisce l'anteprima del thread principale, e le anteprime di un thread figlio non vengono mai ripubblicate su di esso. Per osservare il testo di un subagente mentre il modello lo genera, apri il flusso del thread di quel subagente. Il percorso del flusso di un thread termina con `/threads/{thread_id}/stream`. `/events/stream` esiste solo a livello di sessione, quindi non esiste alcun endpoint `/threads/{thread_id}/events/stream`. `event_start` e `event_delta` hanno la stessa forma sul flusso di un thread e sul flusso a livello di sessione, e il pattern [accumulare e riconciliare](https://platform.claude.com/docs/it/managed-agents/event-deltas#accumulate-and-reconcile) si applica così come descritto. Esegui un'istanza di accumulatore per ogni connessione di flusso. ```bash cURL # Lo stream del thread accetta lo stesso parametro event_deltas[] dello stream della sessione. # Codifica in percentuale le parentesi quadre (%5B%5D) e metti l'URL tra virgolette. curl --fail-with-body -sS -N \ "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream?beta=true&event_deltas%5B%5D=agent.message" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "accept: text/event-stream" ``` ```bash CLI # Lo stream del thread accetta lo stesso parametro event_deltas dello stream di sessione, # un flag --event-delta per ogni tipo di evento da mostrare in anteprima. ant beta:sessions:threads:events stream \ --session-id "$SESSION_ID" \ --thread-id "$THREAD_ID" \ --event-delta agent.message ``` ```python Python # Elenca i thread della sessione e scegli un figlio: i thread figli hanno parent_thread_id # non null, mentre il parent_thread_id del thread primario è null. child_thread = next( thread for thread in client.beta.sessions.threads.list(session.id) if thread.parent_thread_id is not None ) # Lo stream del thread figlio accetta lo stesso parametro event_deltas dello # stream della sessione. with client.beta.sessions.threads.events.stream( child_thread.id, session_id=session.id, event_deltas=["agent.message"], ) as stream: for event in stream: match event.type: case "event_delta": print(event.delta.content.text, end="") case "agent.message": # L'evento nel buffer è il record autorevole; renderizzane il contenuto print() for block in event.content: if block.type == "text": print(block.text, end="") print() case "session.thread_status_idle": break ``` ```typescript TypeScript // Elenca i thread della sessione e scegli un figlio: i thread figli hanno un // parent_thread_id non null, mentre il parent_thread_id del thread primario è null. let childThreadId: string | undefined; for await (const thread of client.beta.sessions.threads.list(session.id)) { if (thread.parent_thread_id !== null) { childThreadId = thread.id; break; } } if (!childThreadId) { throw new Error("No child thread found"); } // Lo stream del thread figlio accetta lo stesso parametro event_deltas dello // stream della sessione. const stream = await client.beta.sessions.threads.events.stream(childThreadId, { session_id: session.id, event_deltas: ["agent.message"] }); threadDeltas: for await (const event of stream) { switch (event.type) { case "event_delta": process.stdout.write(event.delta.content.text); break; case "agent.message": { // L'evento bufferizzato è il record autorevole; visualizzane il contenuto. process.stdout.write("\n"); const text = event.content .map((block) => (block.type === "text" ? block.text : "")) .join(""); console.log(text); break; } case "session.thread_status_idle": break threadDeltas; } } stream.controller.abort(); ``` ```csharp C# // Elenca i thread della sessione e scegli un figlio: i thread figli hanno parent_thread_id // non nullo, mentre il parent_thread_id del thread primario è null. var threads = await client.Beta.Sessions.Threads.List(session.ID); var childThread = threads.Items.First(thread => thread.ParentThreadID is not null); // Lo stream del thread figlio accetta lo stesso parametro event_deltas dello // stream della sessione. using var stream = await client.Beta.Sessions.Threads.Events.WithRawResponse.StreamStreaming( childThread.ID, new() { SessionID = session.ID, EventDeltas = [BetaManagedAgentsDeltaType.AgentMessage] } ); await foreach (var streamEvent in stream.Enumerate()) { if (streamEvent.TryPickDeltaEvent(out var delta)) { Console.Write(delta.Delta.Content.Text); } else if (streamEvent.TryPickAgentMessageEvent(out var message)) { // L'evento bufferizzato è il record autorevole; mostra il suo contenuto. Console.WriteLine(); var text = string.Concat(message.Content.Select(block => block.TryPickBetaManagedAgentsTextBlock(out var textBlock) ? textBlock.Text : "")); Console.WriteLine(text); } else if (streamEvent.TryPickSessionThreadStatusIdleEvent(out _)) { break; } } ``` ```go Go // Elenca i thread della sessione e scegli un figlio: i thread figli hanno parent_thread_id // non null, mentre il parent_thread_id del thread primario è null. var childThreadID string threads := client.Beta.Sessions.Threads.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionThreadListParams{}) for threads.Next() { if thread := threads.Current(); thread.ParentThreadID != "" { childThreadID = thread.ID break } } if err := threads.Err(); err != nil { panic(err) } // Lo stream del thread figlio accetta lo stesso parametro event_deltas dello // stream di sessione; esegui un ciclo di lettura per ogni connessione stream. stream := client.Beta.Sessions.Threads.Events.StreamEvents(ctx, childThreadID, anthropic.BetaSessionThreadEventStreamParams{ SessionID: session.ID, EventDeltas: []anthropic.BetaManagedAgentsDeltaType{ anthropic.BetaManagedAgentsDeltaTypeAgentMessage, }, }) threadDeltas: for stream.Next() { switch event := stream.Current().AsAny().(type) { case anthropic.BetaManagedAgentsDeltaEvent: fmt.Print(event.Delta.Content.Text) case anthropic.BetaManagedAgentsAgentMessageEvent: // L'evento bufferizzato è il record autorevole; renderizza il suo contenuto. fmt.Println() // lista a tipo concreto: BetaManagedAgentsTextBlock for _, block := range event.Content { fmt.Print(block.Text) } fmt.Println() case anthropic.BetaManagedAgentsSessionThreadStatusIdleEvent: break threadDeltas } } if err := stream.Err(); err != nil { panic(err) } stream.Close() ``` ```java Java // Elenca i thread della sessione e scegli un figlio: i thread figli hanno un // parent_thread_id non null, mentre il parent_thread_id del thread primario è null. var childThread = client.beta().sessions().threads().list(session.id()).autoPager().stream() .filter(thread -> thread.parentThreadId().isPresent()) .findFirst() .orElseThrow(); // Lo stream del thread figlio accetta lo stesso parametro event_deltas dello stream // della sessione. La sua classe params ha lo stesso nome semplice di quella di sessione, quindi qualificala. try (var stream = client.beta().sessions().threads().events().streamStreaming( childThread.id(), com.anthropic.models.beta.sessions.threads.events.EventStreamParams.builder() .sessionId(session.id()) .addEventDelta(BetaManagedAgentsDeltaType.AGENT_MESSAGE) .build() )) { Iterable events = stream.stream()::iterator; threadDeltas: for (var event : events) { switch (event.type().value()) { case EVENT_DELTA -> IO.print(event.asEventDelta().delta().content().text()); case AGENT_MESSAGE -> { // L'evento bufferizzato è il record autorevole; renderizza il suo contenuto. IO.println(); event.asAgentMessage().content().forEach(block -> block.text().ifPresent(textBlock -> IO.print(textBlock.text()))); IO.println(); } case SESSION_THREAD_STATUS_IDLE -> { break threadDeltas; } } } } ``` ```php PHP use Anthropic\Beta\Sessions\BetaManagedAgentsDeltaEvent; use Anthropic\Beta\Sessions\BetaManagedAgentsDeltaType; use Anthropic\Beta\Sessions\Events\ManagedAgentsAgentMessageEvent; use Anthropic\Beta\Sessions\Events\ManagedAgentsSessionThreadStatusIdleEvent; use Anthropic\Beta\Sessions\Events\ManagedAgentsTextBlock; // Elenca i thread della sessione e scegline uno figlio: i thread figli hanno un // parentThreadID non null, mentre il parentThreadID del thread principale è null. $childThread = null; foreach ($client->beta->sessions->threads->list($session->id)->pagingEachItem() as $thread) { if ($thread->parentThreadID !== null) { $childThread = $thread; break; } } // Lo stream del thread figlio accetta lo stesso parametro eventDeltas dello // stream della sessione. $stream = $client->beta->sessions->threads->events->streamStream( $childThread->id, sessionID: $session->id, eventDeltas: [BetaManagedAgentsDeltaType::AGENT_MESSAGE], ); foreach ($stream as $event) { switch (true) { case $event instanceof BetaManagedAgentsDeltaEvent: echo $event->delta->content->text; break; case $event instanceof ManagedAgentsAgentMessageEvent: // L'evento nel buffer è il record autorevole; visualizzane il contenuto echo "\n"; foreach ($event->content as $block) { if ($block instanceof ManagedAgentsTextBlock) { echo $block->text; } } echo "\n"; break; case $event instanceof ManagedAgentsSessionThreadStatusIdleEvent: break 2; // Break foreach loop } } $stream->close(); ``` ```ruby Ruby # Elenca i thread della sessione e scegli un figlio: i thread figli hanno un # parent_thread_id non nullo, mentre il parent_thread_id del thread primario è null. child_thread = client.beta.sessions.threads.list(session.id).to_enum.find { it.parent_thread_id } # Lo stream del thread figlio accetta lo stesso parametro event_deltas dello # stream della sessione. stream = client.beta.sessions.threads.events.stream_events( child_thread.id, session_id: session.id, event_deltas: [Anthropic::Beta::BetaManagedAgentsDeltaType::AGENT_MESSAGE] ) stream.each do |event| case event when Anthropic::Beta::BetaManagedAgentsDeltaEvent print event.delta.content.text when Anthropic::Beta::Sessions::BetaManagedAgentsAgentMessageEvent # L'evento bufferizzato è il record autorevole; mostrane il contenuto. puts event.content.each { print it.text } puts when Anthropic::Beta::Sessions::BetaManagedAgentsSessionThreadStatusIdleEvent break else # ignora gli altri tipi di evento end end ``` Il ciclo di lettura termina su [`session.thread_status_idle`](https://platform.claude.com/docs/it/managed-agents/reference#event-types), l'evento emesso quando il turno del thread di sessione termina e il thread diventa inattivo. ## Limitazioni * **Best effort:** Sotto carico, il server potrebbe scartare i delta di un evento. Quando ciò accade, ricevi un prefisso contiguo del testo e poi nessun altro delta per quell'evento. L'`agent.message` bufferizzato arriva comunque completo. Non considerare mai definitiva un'anteprima accumulata. * **Nessuna riproduzione alla riconnessione:** I delta vengono consegnati solo alla connessione che li ha attivati, finché è aperta. Questo vale sia per il flusso a livello di sessione sia per ogni flusso di thread di sessione. Una connessione aperta dopo l'inizio di una richiesta al modello non riceve alcun delta per quell'evento in corso. Non c'è modo di richiedere nuovamente i delta persi. * **Un solo thread, solo testo:** Le anteprime coprono il testo dell'assistente sul [thread che la connessione sta leggendo](https://platform.claude.com/docs/it/managed-agents/event-deltas#preview-session-thread-events). L'uso degli strumenti, i risultati degli strumenti e i risultati MCP non vengono mai visualizzati in anteprima. * **Mai persistiti:** `event_start` e `event_delta` esistono solo sul flusso in tempo reale. Non compaiono nella cronologia degli eventi della sessione (`GET /v1/sessions/{session_id}/events`) né nella cronologia degli eventi di alcun thread di sessione. ## Risoluzione dei problemi delle anteprime | Cosa vedi | Cosa significa | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Un flusso con eventi bufferizzati ma nessun `event_start` o `event_delta` | La connessione che stai leggendo non ha attivato le anteprime, oppure il turno non ha mai interessato il thread di cui stai facendo lo streaming. `event_deltas[]` si applica per connessione, non per sessione. Per scoprire quale thread è stato eseguito, elenca i thread della sessione (`GET /v1/sessions/{session_id}/threads`). | | Un flusso che si interrompe durante un'anteprima | I delta non vengono riprodotti. Segui la [procedura di riconnessione](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#reconnect-without-missing-events): riapri il flusso ed elenca la cronologia degli eventi. La cronologia include tutti gli eventi bufferizzati emessi mentre eri disconnesso, incluso l'`agent.message` che la tua anteprima stava aspettando. | | Un errore 404 sull'URL del flusso | Il percorso o un ID è errato, oppure la richiesta non contiene alcun header beta managed-agents. Gli endpoint dei thread sono soggetti a beta, quindi senza l'header non esistono. | | Un errore 400 che menziona `event_deltas` | Sono accettati solo `agent.message` e `agent.thinking`. | ## Passaggi successivi Invia eventi, ricevi risposte in streaming e interrompi o reindirizza la tua sessione durante l'esecuzione. Coordina più agenti all'interno di una singola sessione.