AssistantMessage для каждого непустого блока содержимого, такого как текстовый блок или вызов инструмента, после того как Claude завершит генерацию этого блока. Чтобы получать добавочные обновления по мере генерации текста и вызовов инструментов, включите потоковую передачу частичных сообщений.
Включение потоковой передачи выходных данных
Чтобы включить потоковую передачу, установитеinclude_partial_messages (Python) или includePartialMessages (TypeScript) в значение true в ваших параметрах. Это заставляет SDK выдавать сообщения StreamEvent, содержащие необработанные события API по мере их поступления, в дополнение к обычным AssistantMessage и ResultMessage.
Ваш код затем должен:
- Проверить тип каждого сообщения, чтобы отличить
StreamEventот других типов сообщений - Для
StreamEventизвлечь полеeventи проверить егоtype - Искать события
content_block_delta, гдеdelta.type— этоtext_delta, которые содержат фактические текстовые фрагменты
StreamEvent, затем для content_block_delta, затем для text_delta:
Справочник StreamEvent
Когда включены частичные сообщения, вы получаете необработанные события потоковой передачи Claude API, обёрнутые в объект. Тип имеет разные названия в каждом SDK:- Python:
StreamEvent(импортируется изclaude_agent_sdk.types) - TypeScript:
SDKPartialAssistantMessageсtype: 'stream_event'
parent_tool_use_id всегда имеет значение None в Python и null в TypeScript. События потока генерируются только для основной сессии; дельты на уровне токенов от подагентов не пересылаются. Чтобы атрибутировать вывод подагенту, используйте полные сообщения, которые содержат parent_tool_use_id. См. Обнаружение вызова подагента.
Claude Code устанавливает user_message_uuid на первом событии потока без ping в ходе хода, и снова, когда изменяется сообщение, на которое отвечает ход, в соответствии с условиями в user_message_uuid. Python StreamEvent не предоставляет это поле.
Поле event содержит необработанное событие потока из Claude API. Распространённые типы событий включают:
Поток сообщений
Claude Code выдаетAssistantMessage по мере завершения каждого непустого блока содержимого, поэтому ответ с текстовым блоком и вызовом инструмента дает два объекта AssistantMessage. Каждый из них содержит только свой собственный блок содержимого, и оба имеют одинаковый ID сообщения, который вы читаете как message.message.id в TypeScript и message.message_id в Python. При включенных частичных сообщениях каждое AssistantMessage поступает до события content_block_stop этого блока, и вы получаете сообщения в таком порядке:
StreamEvent. Распространенные типы включают SystemMessage (инициализация сеанса), AssistantMessage (полные блоки содержимого), ResultMessage (финальный результат) и компактное граничное сообщение, указывающее на то, когда история разговора была сжата (SDKCompactBoundaryMessage в TypeScript; SystemMessage с подтипом "compact_boundary" в Python).
Обработка оборванного потока
Если поток обрывается посреди сообщения, например когда вы прерываете ход или разрывается соединение, вы всё равно получаетеmessage_stop этого сообщения до завершения хода. Оборванный текстовый блок или блок размышлений также получает свой content_block_stop. Оборванный вызов инструмента его не получает, поэтому если message_stop поступает, пока блок вызова инструмента ещё открыт, считайте входные данные этого вызова неполными.
До Claude Code v2.1.290 оборванный поток мог завершить ход без message_stop, поэтому ответ, который вы отображаете на основе событий потока, мог оставаться показанным как выполняющийся. TypeScript Agent SDK включает Claude Code v2.1.290 или новее начиная с v0.3.290, а Python Agent SDK — начиная с v0.2.164. Если ответ остается показанным как выполняющийся после завершения хода, обновите SDK.
Потоковая передача вызовов инструментов
Вызовы инструментов также передаются потоком добавочно. Вы можете отследить, когда инструменты начинают работу, получить их входные данные по мере их генерации и увидеть, когда они завершаются. Пример ниже отслеживает текущий вызываемый инструмент и накапливает входные данные JSON по мере их поступления. Он использует три типа событий:content_block_start: инструмент начинает работуcontent_block_deltaсinput_json_delta: поступают фрагменты входных данныхcontent_block_stop: вызов инструмента завершен
Создание пользовательского интерфейса потоковой передачи
Этот пример объединяет потоковую передачу текста и инструментов в единый пользовательский интерфейс. Он отслеживает, выполняет ли агент в настоящее время инструмент (используя флагin_tool), чтобы показать индикаторы состояния, такие как [Using Read...], пока работают инструменты. Текст передается потоком нормально, когда инструмент не используется, а завершение инструмента вызывает сообщение “done”. Этот паттерн полезен для интерфейсов чата, которым нужно показывать прогресс во время многошаговых задач агента.
Известные ограничения
- Structured output: при включённых частичных сообщениях JSON передаётся потоком как невалидированные
input_json_deltaфрагменты инструмента, и только валидированный результат попадает в финальныйResultMessage.structured_output. Подробнее см. в разделе structured outputs.
Следующие шаги
Теперь, когда вы можете передавать текст и вызовы инструментов потоком в реальном времени, изучите эти связанные темы:- Интерактивные и одноразовые запросы: выберите режим ввода для вашего случая использования
- Структурированные выходные данные: получайте типизированные ответы JSON от агента
- Разрешения: контролируйте, какие инструменты может использовать агент