Прямые HTTP-запросы

SDK есть только для Python, контракт — для всех. Базовый адрес прода:

https://api.cloud.agentums.ru

Авторизация

Один заголовок на все запросы:

Authorization: Bearer ak_ваш_токен

Токен выпускается в приложении app.agentums.ru: Настройки → API-токены. Никаких других заголовков добавлять не нужно.

Форма ответа

Успех — тело схемы маршрута, без обёртки:

{ "answer": "Договор действует до 31.12.2026.", "citations": [ … ], "session_id": "…" }

Ошибка приложения — конверт с текстом причины:

{ "success": false, "data": null, "error": "Пустой запрос" }

Ошибка валидации (422) приходит в стандартном виде FastAPI — список detail с указанием поля. Это единственная форма, выпадающая из двух предыдущих, и обрабатывать её стоит отдельно.

Загрузить файл

curl -X POST https://api.cloud.agentums.ru/v1/objects \
  -H "Authorization: Bearer ak_…" \
  -F "file=@contract.pdf"

Ответ придёт со status: "pending": обработка идёт фоном. Дождитесь готовности, опрашивая карточку объекта, — до этого поиск по содержимому файла ничего не найдёт.

curl -H "Authorization: Bearer ak_…" \
  https://api.cloud.agentums.ru/v1/objects/<object_id>

Спросить по документам

curl -X POST https://api.cloud.agentums.ru/v1/ask \
  -H "Authorization: Bearer ak_…" \
  -H "Content-Type: application/json" \
  -d '{"query": "Какой срок действия договора?"}'

Верните полученный session_id в следующем запросе — и разговор продолжится с оглядкой на сказанное.

Фоновые задачи

Конвертация, операции над PDF, перевод, сборка документа отвечают task_id. Готовность спрашивается у соответствующего */status-маршрута:

curl -H "Authorization: Bearer ak_…" \
  https://api.cloud.agentums.ru/v1/objects/convert-status/<task_id>

Пока done: false — работа идёт. Разумный интервал опроса — несколько секунд.

Поток агента

POST /v1/agent/chat отвечает потоком SSE: строки вида data: {…}. Типы кадров — start, token, tool_start, tool_end, paused, error, done.

Два правила, которые легко нарушить:

• paused — конец потока, done не придёт. Агент ждёт вашего решения по опасному действию; продолжают через POST /v1/agent/continue, передавая решения по всем инструментам из события одним вызовом.
• error — не конец потока. За ним могут прийти ещё токены и done.

Кадры, которые не разобрались как JSON, игнорируйте: битый кадр не должен ронять уже идущий ответ. Пустые строки и строки-комментарии (: ping) — разделители потока.

Что дальше

• Справочник API — все маршруты, схемы и коды ответов
• Ошибки и повторы — что повторять можно, а что бессмысленно
• Машинная спека: /openapi.json — импортируется в Postman, Insomnia и генераторы клиентов