Skip to main content
Вам нужны идентификатор агента и ключ с доступом full (см. Получите API-ключ). Все примеры читают их из трёх переменных окружения:

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

POST /v1/agents/{agent_id}/chat отправляет одно сообщение пользователя и ждёт ответа. Кроме Content-Type, важны два заголовка:
  • Authorization: Bearer <key>
  • Idempotency-Key: любое уникальное значение длиной 1-255 символов на логический запрос. UUID — хороший выбор. Заголовок обязателен на обоих эндпоинтах чата; см. Идемпотентность.

Прочитать ответ

  • request_id также возвращается в заголовке X-Request-ID.
  • conversation_id — диалог, в который сохранён обмен. Отправьте ещё одно сообщение с тем же external_user_id, и оно продолжит этот диалог.
  • usage.charged_usd — десятичная строка с 8 знаками: сколько этот запрос стоил балансу владельца.
Ответ может занять время, если агент использует инструменты или большую базу знаний. Задайте запросу щедрый таймаут (в примерах — 120 секунд) или используйте потоковый эндпоинт, чтобы показывать текст по мере генерации.

Продолжить диалог

Отправьте второе сообщение с тем же external_user_id и новым Idempotency-Key:
Агент видит предыдущий обмен как историю. Если отправить сообщение для внешнего пользователя, пока его предыдущий ответ ещё генерируется, вернётся 409 conversation_busy с Retry-After: 2; подождите и повторите.

Что дальше

Стриминг

Показывайте ответ по мере генерации.

Диалоги

Список диалогов и постраничное чтение сообщений.

Ошибки

Все коды, которые может вернуть API, и что с ними делать.

Справочник API

Полные схемы запросов и ответов, с плейграундом.