Отправка сообщений

Отправка сообщения агенту и получение ответа — целиком или потоком событий, а также остановка генерации ответа.

Отправка сообщения

POST /v1/chat

Тело запроса

Новый диалог и переменные старта

• Сообщение без dialog_id создаёт новый диалог, и в ответе приходит его dialog_id. Название диалога формируется так же, как в чате по ссылке: сначала это начало первого сообщения, затем название, которое предложит модель.

• Значения переменных старта передаются только в первом сообщении, в поле variables. Дальше диалог работает с сохранёнными значениями; variables вместе с dialog_id — ошибка invalid_request.

• API проверяет переменные так же, как чат: переменная, которой нет у агента, обязательная переменная без значения, значение неверного типа, значение не из списка options или длиннее max_length — ошибка invalid_request.

• Для файловой переменной действует её собственный предел размера (max_size_mb в описании переменной): он проверяется здесь, при отправке первого сообщения, а не при загрузке файла.

• Значение переменной типа file — идентификатор загруженного файла, типа files — список идентификаторов.

Файлы в сообщении

• Сначала загрузите файлы с тем же user_id и передайте их идентификаторы в files.

• Файлы сверяются с настройками агента при отправке: если загрузка файлов у агента выключена — file_upload_disabled, если тип файла не разрешён — file_type_blocked, если файлов больше, чем разрешено, — too_many_files. Настройки — в поле file_upload настроек агента.

• Файл, загруженный другим user_id, передать нельзя: ошибка invalid_file_id.

Ответ без потока

При stream: false или без поля stream API дожидается конца генерации и возвращает 200 с объектом Reply:

Если генерация не удалась, ответ приходит с HTTP-статусом и кодом этой ошибки — см. Ошибки.

curl https://api.evo-ai.ru/v1/chat \
  -H "Authorization: Bearer evo_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-42",
    "text": "Какие сроки ответа на претензию?",
    "variables": {"company": "ООО «Ромашка»"}
  }'

{
  "message_id": "0c9a3f52-1e7b-4d26-8f40-5a2b9c7d3e61",
  "dialog_id": "7d4e2b18-9c05-4a3f-b6e1-2f8c0a9d5b73",
  "answer": "Срок ответа на претензию -- 30 календарных дней, если договор не устанавливает другой срок.",
  "sources": [],
  "tools": [],
  "files": [],
  "usage": {"input_tokens": 812, "output_tokens": 64, "total_tokens": 876},
  "created_at": "2026-09-24T10:15:00Z"
}

Source — источник ответа:

Любое поле Source может быть null, если в сохранённом источнике его нет. Источники приходят, только если у агента включено Отображение источников; иначе sources — пустой список. В уже начатом диалоге действуют текущие опубликованные настройки агента. Файловые базы знаний агент читает целиком, источников по ним нет.

MessageFile — файл сообщения:

Поток ответа

При stream: true API отвечает Content-Type: text/event-stream. Каждое событие — строка event: <имя>, строка data: <JSON> и пустая строка. Каждые 10 секунд в потоке приходит строка-комментарий : keep-alive, чтобы соединение не закрылось по простою, — пропускайте её.

Других событий в потоке нет. Поток всегда заканчивается событием generation.finished или generation.failed. Если генерация сорвалась в самом начале, в generation.started может прийти generation_id: null, а следом — generation.failed.

curl -N https://api.evo-ai.ru/v1/chat \
  -H "Authorization: Bearer evo_agent_..." \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user-42", "dialog_id": "7d4e2b18-9c05-4a3f-b6e1-2f8c0a9d5b73", "text": "А если срок пропущен?", "stream": true}'

event: generation.started
data: {"generation_id": "4f8b2c61-7a3d-4e95-b0c2-9d1e6f3a8b47", "dialog_id": "7d4e2b18-9c05-4a3f-b6e1-2f8c0a9d5b73", "message_id": "a3e1c7d9-5b24-4f86-9e0a-6c2d8b4f1e53"}

event: answer.delta
data: {"text": "Если срок ответа пропущен, "}

event: answer.delta
data: {"text": "вы можете обратиться в суд."}

event: generation.finished
data: {"message_id": "a3e1c7d9-5b24-4f86-9e0a-6c2d8b4f1e53", "dialog_id": "7d4e2b18-9c05-4a3f-b6e1-2f8c0a9d5b73", "sources": [], "usage": {"input_tokens": 905, "output_tokens": 18, "total_tokens": 923}}

Если соединение оборвалось посреди потока, генерация не останавливается: ответ появится в истории диалога, когда агент его закончит.

Остановка генерации

POST /v1/generations/{generation_id}/stop

Останавливает генерацию ответа. generation_id приходит в первом событии потока — generation.started.

Тело запроса

Ответ

204 — без тела.

• Поток завершается событием generation.finished.

• Текст, который уже пришёл в событиях answer.delta, остаётся только у вашего приложения: в истории диалога у этого сообщения ответ пустой, без ошибки.

• Остановка уже завершившейся генерации или генерации другого user_id ничего не делает и тоже отвечает 204.

curl -X POST https://api.evo-ai.ru/v1/generations/4f8b2c61-7a3d-4e95-b0c2-9d1e6f3a8b47/stop \
  -H "Authorization: Bearer evo_agent_..." \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user-42"}'

Ошибки

Ошибки, которые получает запрос отправки сообщения:

Ошибки генерации — model_unavailable, generation_failed, generation_timeout (504), agent_step_limit_reached, tool_call_too_large, tool_access_denied (403), document_too_large, document_unreadable:

• Обнаружена до начала ответа — например, модель агента недоступна, инструмент недоступен пространству, файл не помещается в контекст или не читается. API отвечает HTTP-ошибкой с этим кодом и при stream: true тоже; сообщение в историю не попадает.

• Случилась во время генерации. Без потока — HTTP-ответ с кодом ошибки, в потоке — событие generation.failed; в истории у сообщения ошибка в поле error. В generation.failed может прийти и credits_exhausted или internal_error.

Сообщение, которое API отклонило до обращения к агенту (например, с invalid_request), в историю диалога не попадает.

Все коды — на странице Ошибки.