К содержимому

Продолжение задачи и уточнения ​

Сохраните связь тикета с session_id. При новом событии сначала проверьте, завершился ли предыдущий запуск.

Для следующих запусков сессия должна быть создана с allow_multiple_runs: true. В режиме по умолчанию создавайте новую сессию на следующую задачу. Уточнения работающему агенту доступны в обоих режимах.

Как проверить состояние ​

Вызовите получение сессии, подставив её ID вместо {sid}:

http
GET /api/v1/sessions/{sid}

В ответе active_run_id содержит ID незавершённого запуска или null, если такого запуска нет. Поля status и phase описывают последний запуск. Например, такой фрагмент ответа означает, что агент работает:

json
{
  "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:

json
{
  "messages": [
    {
      "text": "The customer provided the error: export permission denied.",
      "external_key": "support.example.com:event:106"
    }
  ]
}

Уточнение во время работы ​

Отправьте сообщение запуску на /api/v1/sessions/{sid}/runs/{rid}/messages:

json
{
  "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. Сохраните этот исход, не повторяя автоматически действия в другой сессии. Идемпотентный повтор принятого запроса сохраняет исходное подтверждение даже после удаления.

Остановка ​

Для остановки вызовите отмену запуска. Отмена не откатывает изменения, которые агент уже сделал во внешней системе.