Стриминг (SSE)
Нативный API стримит через Server-Sent Events по двухшаговому протоколу: вы запускаете ход, затем подписываетесь на его устойчивый журнал событий. Разделение делает стрим возобновляемым — оборванное соединение переподключается и доигрывает с места обрыва, а один ход можно смотреть из нескольких вкладок.
Нужен drop-in в одну строку?
Если вам нужен только потоковый текст и вы уже используете OpenAI SDK — OpenAI-совместимый эндпоинт стримит в одном запросе и проще. Эта страница описывает нативный протокол и полный набор его событий.
Протокол
Запустите ход
POST /api/v1/sessions/stream не стримит — он возвращает 202 Accepted с идентификаторами хода, запущенного в фоне.
Подпишитесь на журнал событий
GET /api/v1/sessions/{session_id}/messages/{message_id}/stream возвращает text/event-stream и доигрывает все события этого хода. Каждый фрейм несёт id: — сохраняйте последний, чтобы возобновиться.
Поля запроса
Тело POST /sessions/stream принимает:
| Field | Type | Description |
|---|---|---|
| messagerequired | string | Ход пользователя. Обязателен message либо document_ids. |
| session_id | string | Передайте session_id, чтобы продолжить предыдущий разговор. Опустите для нового — ответ вернёт новый id. |
| agent_id | string | Выполнить ход под профилем конкретного агента и выданными ему коннекторами. См. Агенты. |
| document_ids | array | Прикрепить ранее загруженные документы к ходу по id. |
Типы событий
Каждый фрейм — это data: и JSON-объект с дискриминатором type. Это стабильные публичные типы событий — обрабатывайте нужные и игнорируйте любой type, который не распознали; набор расширяемый.
| Тип | Значение |
|---|---|
start | Ход начался. Несёт session_id. |
delta | Инкремент текста ассистента — добавляйте content для живого рендера. |
tool_started | Начался вызов инструмента. Несёт tool_name, label, iteration. |
tool_completed | Инструмент завершился. Несёт success, message, duration_ms. |
artifact_start | Начал стримиться файл/артефакт. Несёт artifact_id, artifact_type, title. |
artifact_delta | Чанк содержимого артефакта (content_chunk, chunk_index). |
artifact_complete | Артефакт готов. Несёт version, content_type, опционально download_url. |
artifact_update | Ранее завершённый артефакт был изменён. |
complete | Терминальный успех. Несёт final_response, счётчики токенов и artifacts. |
error | Терминальная ошибка. Несёт код error, message, retryable, user_message. |
cancelled | Ход остановлен. Несёт reason (user_stop, timeout, …) и partial_response, если есть. |
paused | Ход приостановлен в ожидании пробуждения (форма, таймер или rate-limit). Стрим закрывается штатно — возобновите позже с теми же id. |
form_request | Агенту нужен ввод. Несёт form_kind (clarify | integration | signature | approval), form_id и payload. |
Канонический ответ — в событии complete
Рендерьте текст delta вживую для UX, но авторитетный ответ — это complete.final_response, а не склейка дельт. Агент может переписать ответ по ходу, поэтому дельты — промежуточный нарратив, а final_response равен сохранённому сообщению.
Также могут появляться транзиентные диагностические события (thinking, heartbeat, retry_notification, browser_frame) — они не входят в стабильный контракт, их можно пропускать.
Возобновление оборванного стрима
Эндпоинт подписки идемпотентен и безопасен для нескольких вкладок. Чтобы возобновиться после обрыва, верните id последнего фрейма — заголовком Last-Event-ID или query-параметром ?since= — и сервер доиграет только пропущенное.
Ответ на form_request
Когда приходит form_request, ход приостанавливается (можно также увидеть событие paused). Отправьте ответ пользователя обычным POST /sessions/stream с тем же session_id — платформа направит его в ожидающую форму, а не начнёт новый ход, и исходный ход возобновится на своём стриме.
Остановка хода
POST /api/v1/sessions/{session_id}/stop отменяет активный ход. Идемпотентен и всегда возвращает 204; стрим затем отдаёт событие cancelled с reason: "user_stop".
Полезные ссылки