Перейти к основному содержанию
По умолчанию Agent SDK выдает полные объекты AssistantMessage после того, как Claude завершит генерацию каждого ответа. Чтобы получать добавочные обновления по мере генерации текста и вызовов инструментов, включите потоковую передачу частичных сообщений, установив include_partial_messages (Python) или includePartialMessages (TypeScript) в значение true в ваших параметрах.
На этой странице рассматривается потоковая передача выходных данных (получение токенов в реальном времени). Для режимов ввода (как вы отправляете сообщения), см. Отправка сообщений агентам. Вы также можете передавать ответы потоком с помощью 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:
  • Python: StreamEvent (импортируется из claude_agent_sdk.types)
  • TypeScript: SDKPartialAssistantMessage с type: 'stream_event'
Оба содержат необработанные события Claude API, а не накопленный текст. Вам нужно самостоятельно извлекать и накапливать текстовые дельты. Вот структура каждого типа:
Поле parent_tool_use_id всегда имеет значение None в Python и null в TypeScript. События потока генерируются только для основной сессии; дельты на уровне токенов от подагентов не пересылаются. Чтобы атрибутировать вывод подагенту, используйте полные сообщения, которые содержат parent_tool_use_id. См. Обнаружение вызова подагента. Поле event содержит необработанное событие потоковой передачи из Claude API. Распространенные типы событий включают:

Поток сообщений

С включенными частичными сообщениями вы получаете сообщения в этом порядке:
Без включенных частичных сообщений (include_partial_messages в Python, includePartialMessages в TypeScript) вы получаете все типы сообщений, кроме StreamEvent. Распространенные типы включают SystemMessage (инициализация сеанса), AssistantMessage (полные ответы), ResultMessage (финальный результат) и компактное граничное сообщение, указывающее на то, когда история разговора была сжата (SDKCompactBoundaryMessage в TypeScript; SystemMessage с подтипом "compact_boundary" в Python).

Потоковая передача текстовых ответов

Чтобы отобразить текст по мере его генерации, ищите события content_block_delta, где delta.type — это text_delta. Они содержат добавочные текстовые фрагменты. Пример ниже выводит каждый фрагмент по мере его поступления:

Потоковая передача вызовов инструментов

Вызовы инструментов также передаются потоком добавочно. Вы можете отследить, когда инструменты начинают работу, получить их входные данные по мере их генерации и увидеть, когда они завершаются. Пример ниже отслеживает текущий вызываемый инструмент и накапливает входные данные JSON по мере их поступления. Он использует три типа событий:
  • content_block_start: инструмент начинает работу
  • content_block_delta с input_json_delta: поступают фрагменты входных данных
  • content_block_stop: вызов инструмента завершен

Создание пользовательского интерфейса потоковой передачи

Этот пример объединяет потоковую передачу текста и инструментов в единый пользовательский интерфейс. Он отслеживает, выполняет ли агент в настоящее время инструмент (используя флаг in_tool), чтобы показать индикаторы состояния, такие как [Using Read...], пока работают инструменты. Текст передается потоком нормально, когда инструмент не используется, а завершение инструмента вызывает сообщение “done”. Этот паттерн полезен для интерфейсов чата, которым нужно показывать прогресс во время многошаговых задач агента.

Известные ограничения

  • Structured output: результат JSON появляется только в финальном ResultMessage.structured_output, а не как потоковые дельта-обновления. Подробнее см. в разделе structured outputs.

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

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