Поток событий и управление

Сессия Managed Agents общается с вашим приложением через события: вы отправляете входящие события в сессию, а всё, что делает агент — сообщения, вызовы инструментов, смены статуса, — приходит обратно потоком событий. Это единственный канал управления работающим агентом, поэтому корректная работа со стримом, реконнектами и статусами определяет надёжность всей интеграции.

Как это работает

Отправлять можно пять типов событий. user.message — обычное сообщение агенту. user.interrupt — прерывание, которое обгоняет очередь других событий. user.tool_confirmation — ответ на запрос подтверждения инструмента при политике разрешений always_ask. user.custom_tool_result — результат кастомного инструмента, который исполняет ваше приложение, а не контейнер. user.define_outcome — постановка цели с рубрикой вместо чат-сообщения. Получать события можно тремя способами: SSE-стрим GET /v1/sessions/{id}/events/stream для реального времени, постраничный список событий (polling) для истории и вебхуки — HMAC-подписанные уведомления с «тонкими» payload, по которым состояние ресурса нужно дозапросить отдельно. Статусы сессии приходят теми же событиями, и у idle-события есть поле stop_reason, объясняющее, почему агент остановился.

Когда применять

SSE-стрим — основной канал: держите его открытым, пока сессия жива, и реагируйте на события по мере поступления. Polling-список используйте для восстановления полной истории — например, после обрыва соединения или при подключении нового наблюдателя. Вебхуки подходят, когда держать долгоживущее соединение неудобно: сервер уведомит о смене состояния сессии, а детали вы дочитаете обычным запросом. user.interrupt применяйте для команд «стоп»: он не встаёт в очередь за уже отправленными сообщениями, а обгоняет её.

Типичные ошибки

Первая и самая дорогая ошибка — отправить стартовое сообщение до открытия стрима: у стрима нет replay, и события, случившиеся до подключения, вы уже не увидите. Правильный порядок — сначала открыть стрим, потом отправлять kickoff. Вторая ошибка — наивный реконнект: после обрыва нужно сначала запросить историю через список событий, а затем дедуплицировать её с живым стримом по id события, иначе часть событий потеряется или задвоится. Третья — завершать цикл по «голому» status_idle: сессия уходит в idle и тогда, когда ждёт вашего действия. Проверяйте stop_reason — значение requires_action означает, что агент заблокирован в ожидании подтверждения инструмента или результата кастомного инструмента, и выходить из цикла нельзя.

Как это работает

Когда применять

Типичные ошибки

Связанные понятия

Полезные ресурсы