API

Запускайте облачных агентов сотрудника из своего кода — ключ из кабинета, задача, ход работы и файлы результата.

API даёт вашим скриптам и сервисам то же, что облачный агент сотрудника в приложении: поручить задачу, дописать уточнение, следить за ходом, остановить и забрать файлы. Агент работает в облаке сотрудника, с его навыками и подключениями, и расходует лимит тарифа как обычная работа. В приложении он виден у сотрудника — во вкладке «Обзор», в разделе «Агенты».

Ключ

Создайте ключ

В личном кабинете откройте «API-ключи», впишите имя ключа — например, «CI» — и нажмите «Создать ключ».

Сохраните его

Ключ показывается один раз: скопируйте его и нажмите «Я сохранил ключ». Ключ начинается с rzm_. Храните его как пароль — в менеджере секретов, а не в git.

Проверьте

Ключ передают в заголовке Authorization:

curl https://svedum.ru/api/v1/me -H "Authorization: Bearer $RAZUM_API_KEY"

Ключ даёт доступ к сотрудникам вашего аккаунта; войти в кабинет по нему нельзя. Ключ, который больше не нужен или мог утечь, отзовите — «Отозвать» в списке ключей: запросы с ним сразу перестают проходить.

Поручить задачу

Агента запускают у конкретного сотрудника. ID сотрудника — в ссылке на него: «В браузере» в его профиле копирует адрес вида https://svedum.ru/workbench/employees/<id>.

curl https://svedum.ru/api/v1/agents \
  -H "Authorization: Bearer $RAZUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "<id сотрудника>",
    "prompt": { "text": "Сравни цены пяти конкурентов и сведи в таблицу" },
    "client_request_id": "price-check-2026-10-15"
  }'

В ответе — id агента, run_id его первого хода и status. Поля запроса:

employee_id и prompt.text — обязательны.
repo и base_ref — репозиторий GitHub и ветка, если задача про код. → Облачные агенты
client_request_id — ключ повтора: запрос с тем же значением второго агента не запустит. Ставьте его, если ваш код повторяет запросы при сбоях сети.
model — модель агента: ref из GET /models. Без поля агент работает на модели сотрудника, с моделью не из списка запрос вернёт ошибку 400.

Следить и управлять

Запрос	Что делает
`GET /agents/{id}`	Агент и его `status`
`GET /agents/{id}/runs/{run_id}/stream`	События хода потоком (`text/event-stream`)
`POST /agents/{id}/runs`	Новый ход: `{"text": "…"}` — уточнение или следующая задача
`GET /agents/{id}/runs` и `GET /agents/{id}/runs/{run_id}`	Ходы агента
`POST /agents/{id}/runs/{run_id}/cancel`	Остановить ход
`GET /agents/{id}/artifacts`	Файлы, которые сделал агент
`GET /agents/{id}/artifacts/download?path=…`	Скачать файл
`GET /agents/{id}/usage`	Расход агента
`GET /agents?employee_id=…`	Агенты сотрудника, до 100 за запрос; дальше — по `cursor`
`POST /agents/{id}/archive`, `/unarchive`	Убрать агента в архив и вернуть
`DELETE /agents/{id}`	Удалить агента
`GET /models`	Модели, доступные аккаунту

Все пути — от https://svedum.ru/api/v1. status агента:

queued — ждёт места в лимите одновременных задач в облаке;
working — работает;
waiting_user — ждёт ответа на вопрос или разрешение: откройте агента в приложении;
finished — ход закончен.

Если поток оборвался, подключитесь заново с заголовком Last-Event-ID — события придут с того места, где остановились.

Новые поля в ответах могут появляться: читайте те, что нужны, и не отклоняйте ответ с незнакомыми.

КлючСкопировать ссылку

Создайте ключСкопировать ссылку

Сохраните егоСкопировать ссылку

ПроверьтеСкопировать ссылку

Поручить задачуСкопировать ссылку

Следить и управлятьСкопировать ссылку