AssistantMessage für jeden nicht leeren Inhaltsblock, wie einen Textblock oder einen Tool-Aufruf, nachdem Claude die Generierung dieses Blocks abgeschlossen hat. Um inkrementelle Aktualisierungen zu erhalten, während Text und Tool-Aufrufe generiert werden, aktivieren Sie das Streaming von Teillmeldungen.
Ausgabe-Streaming aktivieren
Um Streaming zu aktivieren, setzen Sieinclude_partial_messages (Python) oder includePartialMessages (TypeScript) in Ihren Optionen auf true. Dies führt dazu, dass das SDK StreamEvent-Nachrichten mit rohen API-Ereignissen liefert, die ankommen, zusätzlich zu den üblichen AssistantMessage- und ResultMessage-Objekten.
Ihr Code muss dann:
- Den Typ jeder Nachricht überprüfen, um
StreamEventvon anderen Nachrichtentypen zu unterscheiden - Für
StreamEventdas Feldeventextrahieren und seinentypeüberprüfen - Nach
content_block_delta-Ereignissen suchen, bei denendelta.typegleichtext_deltaist, die die tatsächlichen Text-Chunks enthalten
StreamEvent, dann für content_block_delta, dann für text_delta:
StreamEvent-Referenz
Wenn Teillmeldungen aktiviert sind, erhalten Sie rohe Claude-API-Streaming-Ereignisse, die in einem Objekt verpackt sind. Der Typ hat in jedem SDK unterschiedliche Namen:- Python:
StreamEvent(importieren ausclaude_agent_sdk.types) - TypeScript:
SDKPartialAssistantMessagemittype: 'stream_event'
parent_tool_use_id ist in Python immer None und in TypeScript immer null. Streaming-Ereignisse werden nur für die Hauptsitzung ausgegeben; Token-Level-Deltas von Subagenten werden nicht weitergeleitet. Um die Ausgabe einem Subagenten zuzuordnen, verwenden Sie vollständige Nachrichten, die parent_tool_use_id enthalten. Siehe Subagenten-Aufruf erkennen.
Claude Code setzt user_message_uuid beim ersten Nicht-Ping-Streaming-Ereignis des Durchlaufs und erneut, wenn sich die Nachricht ändert, auf die der Durchlauf antwortet, unter den Bedingungen in user_message_uuid. Der Python StreamEvent macht dieses Feld nicht verfügbar.
Das Feld event enthält das rohe Streaming-Ereignis aus der Claude API. Häufige Ereignistypen sind:
Nachrichtenfluss
Claude Code gibt eineAssistantMessage aus, sobald jeder nicht-leere Inhaltsblock abgeschlossen ist. Eine Antwort mit einem Textblock und einem Werkzeugaufruf ergibt also zwei AssistantMessage-Objekte. Jedes trägt nur seinen eigenen Inhaltsblock, und beide teilen sich dieselbe Nachrichten-ID, die Sie in TypeScript als message.message.id und in Python als message.message_id lesen. Mit aktivierten Teilnachrichten kommt jede AssistantMessage vor dem content_block_stop-Ereignis dieses Blocks an, und Sie erhalten Nachrichten in dieser Reihenfolge:
StreamEvent. Häufige Typen sind SystemMessage (Sitzungsinitialisierung), AssistantMessage (vollständige Inhaltsblöcke), ResultMessage (Endergebnis) und eine kompakte Grenzmarkierungsnachricht, die anzeigt, wann der Gesprächsverlauf komprimiert wurde (SDKCompactBoundaryMessage in TypeScript; SystemMessage mit Subtyp "compact_boundary" in Python).
Einen abgebrochenen Stream behandeln
Wenn ein Stream mitten in einer Nachricht abbricht, etwa weil Sie den Turn unterbrechen oder die Verbindung abreißt, erhalten Sie vor dem Ende des Turns trotzdem dasmessage_stop dieser Nachricht. Ein abgebrochener Text- oder Thinking-Block erhält außerdem sein content_block_stop. Ein abgebrochener Tool-Aufruf dagegen nicht. Wenn also message_stop eintrifft, während der Block eines Tool-Aufrufs noch offen ist, behandeln Sie die Eingabe dieses Aufrufs als unvollständig.
Vor Claude Code v2.1.290 konnte ein abgebrochener Stream den Turn ohne message_stop beenden, sodass eine Antwort, die Sie aus Stream-Ereignissen rendern, weiterhin als laufend angezeigt werden konnte. Das TypeScript Agent SDK enthält ab v0.3.290 Claude Code v2.1.290 oder neuer, das Python Agent SDK ab v0.2.164. Wenn eine Antwort nach dem Ende des Turns weiterhin als laufend angezeigt wird, aktualisieren Sie das SDK.
Tool-Aufrufe streamen
Tool-Aufrufe werden auch inkrementell gestreamt. Sie können verfolgen, wann Tools starten, ihre Eingabe erhalten, während sie generiert wird, und sehen, wann sie abgeschlossen sind. Das folgende Beispiel verfolgt das aktuell aufgerufene Tool und sammelt die JSON-Eingabe, während sie gestreamt wird. Es verwendet drei Ereignistypen:content_block_start: Tool beginntcontent_block_deltamitinput_json_delta: Eingabe-Chunks kommen ancontent_block_stop: Tool-Aufruf abgeschlossen
Streaming-UI erstellen
Dieses Beispiel kombiniert Text- und Tool-Streaming in eine kohärente Benutzeroberfläche. Es verfolgt, ob der Agent gerade ein Tool ausführt (mit einemin_tool-Flag), um Statusanzeigen wie [Using Read...] anzuzeigen, während Tools ausgeführt werden. Text wird normal gestreamt, wenn nicht in einem Tool, und die Tool-Fertigstellung löst eine „done“-Nachricht aus. Dieses Muster ist nützlich für Chat-Schnittstellen, die während mehrstufiger Agent-Aufgaben Fortschritt anzeigen müssen.
Bekannte Einschränkungen
- Strukturierte Ausgabe: Bei aktivierten Teilnachrichten wird das JSON als unkontrollierte
input_json_delta-Chunks eines Tool-Aufrufs gestreamt, und nur das validierte Ergebnis erreicht die finaleResultMessage.structured_output. Weitere Informationen finden Sie unter Strukturierte Ausgaben.
Nächste Schritte
Jetzt, da Sie Text und Tool-Aufrufe in Echtzeit streamen können, erkunden Sie diese verwandten Themen:- Interaktive vs. One-Shot-Abfragen: Wählen Sie zwischen Eingabemodi für Ihren Anwendungsfall
- Strukturierte Ausgaben: Erhalten Sie typisierte JSON-Antworten vom Agent
- Berechtigungen: Kontrollieren Sie, welche Tools der Agent verwenden kann