Продолжение задачи и уточнения
Сохраните связь тикета с session_id. При новом событии сначала проверьте, завершился ли предыдущий запуск.
Для следующих запусков сессия должна быть создана с allow_multiple_runs: true. В режиме по умолчанию создавайте новую сессию на следующую задачу. Уточнения работающему агенту доступны в обоих режимах.
Как проверить состояние
Вызовите получение сессии, подставив её ID вместо {sid}:
GET /api/v1/sessions/{sid}В ответе active_run_id содержит ID незавершённого запуска или null, если такого запуска нет. Поля status и phase описывают последний запуск. Например, такой фрагмент ответа означает, что агент работает:
{
"allow_multiple_runs": true,
"active_run_id": "8a61a76c-73bf-4cbd-a501-26d2f5fcb7a1",
"status": "running",
"phase": "agent"
}Выберите действие по состоянию:
status | Что происходит | Действие коннектора |
|---|---|---|
accepted, starting | Задача принята, окружение и хуки готовятся к работе агента | Сохранить новое сообщение и повторить проверку состояния через несколько секунд |
running | Агент работает | Передать уточнение, подставив ID активного запуска вместо {rid} |
cancelling, finalizing | Запуск останавливается или завершает работу, в том числе хук после агента | Сохранить сообщение и дождаться завершения запуска |
completed, failed, cancelled | Запуск завершён, активного запуска нет | Создать следующий запуск, если разрешены повторные запуски, иначе новую сессию. При ошибке сначала проверить её причину |
Наличие final_message ещё не означает, что запуск завершён: ответ агента может быть готов, пока выполняется after_run. Ориентируйтесь на состояние запуска.
Для подробностей конкретного запуска вызовите получение запуска. Возьмите его ID из active_run_id или last_run_id, если запуск уже завершён.
Следующая задача
Отправьте POST нового запуска на /api/v1/sessions/{sid}/runs:
{
"messages": [
{
"text": "The customer provided the error: export permission denied.",
"external_key": "support.example.com:event:106"
}
]
}Уточнение во время работы
Отправьте сообщение запуску на /api/v1/sessions/{sid}/runs/{rid}/messages:
{
"messages": [
{
"text": "Check access permissions before suggesting another export."
}
]
}В сессии выполняется один запуск за раз. Уточнение не создаёт отдельную параллельную задачу.
Если запрос отклонён
Состояние может измениться между проверкой и отправкой сообщения. Смотрите error.code в ответе API:
409 session_busy: уже есть незавершённый запуск. Перечитайте сессию и выберите действие по таблице.409 multiple_runs_not_allowed: сессия рассчитана на один запуск. Создайте новую сессию с нужным контекстом.409 run_not_accepting_messages: запуск не принимает уточнения. Сохраните сообщение, перечитайте сессию и дождитесь подходящего состояния или создайте следующий запуск, если предыдущий завершён.409 session_unavailableили409 token_limit_exceeded: окружение недоступно или бюджет сессии исчерпан. Создайте новую сессию с необходимым контекстом. Так же поступайте, если завершившийся запуск сообщил об утрате контекста —error.code: context_lost.
Для каждой операции используйте собственный Idempotency-Key, стабильный при повторе. При сетевом таймауте повторите тот же запрос с тем же телом и ключом, чтобы выяснить, был ли он принят. Подробнее о повторах.
Для переиспользуемых песочниц на паузе действует срок хранения. Если внешняя потеря обнаружена после принятия запроса, запуск может асинхронно завершиться с sandbox_lost. Сохраните этот исход, не повторяя автоматически действия в другой сессии. Идемпотентный повтор принятого запроса сохраняет исходное подтверждение даже после удаления.
Остановка
Для остановки вызовите отмену запуска. Отмена не откатывает изменения, которые агент уже сделал во внешней системе.