Skip to main content
По умолчанию Agent SDK выдает полное сообщение AssistantMessage для каждого непустого блока содержимого, такого как текстовый блок или вызов инструмента, после того как Claude завершит генерацию этого блока. Чтобы получать добавочные обновления по мере генерации текста и вызовов инструментов, включите потоковую передачу частичных сообщений.
На этой странице рассматривается потоковая передача выходных данных (получение токенов в реальном времени). Для режимов ввода (как вы отправляете сообщения), см. Отправка сообщений агентам. Вы также можете передавать ответы потоком с помощью Agent SDK через CLI.

Включение потоковой передачи выходных данных

Чтобы включить потоковую передачу, установите include_partial_messages (Python) или includePartialMessages (TypeScript) в значение true в ваших параметрах. Это заставляет SDK выдавать сообщения StreamEvent, содержащие необработанные события API по мере их поступления, в дополнение к обычным AssistantMessage и ResultMessage. Ваш код затем должен:
  1. Проверить тип каждого сообщения, чтобы отличить StreamEvent от других типов сообщений
  2. Для StreamEvent извлечь поле event и проверить его type
  3. Искать события content_block_delta, где delta.type — это text_delta, которые содержат фактические текстовые фрагменты
Пример ниже включает потоковую передачу и выводит текстовые фрагменты по мере их поступления. Обратите внимание на вложенные проверки типов: сначала для StreamEvent, затем для content_block_delta, затем для text_delta:

Справочник StreamEvent

Когда включены частичные сообщения, вы получаете необработанные события потоковой передачи Claude API, обёрнутые в объект. Тип имеет разные названия в каждом SDK: Оба содержат необработанные события Claude API, а не накопленный текст. Вам нужно самостоятельно извлекать и накапливать дельты текста. Поле 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.

Следующие шаги

Теперь, когда вы можете передавать текст и вызовы инструментов потоком в реальном времени, изучите эти связанные темы: