API облачных агентов: агенты Kodagent в вашем коде

15 октября 2026 г.

До сих пор облачного агента запускал человек — из консоли или из Telegram. Но многие задачи для агента появляются не у человека, а в системе. Упала сборка в CI. В трекере появилась задача с нужной меткой. Пора обновить зависимости в двадцати репозиториях. Пользователь вашего сервиса нажал «Сделать прототип». Чтобы отдать такую работу агенту, приходилось идти в консоль и переносить её руками.

Теперь у облачных агентов есть публичный API. Ваш код создаёт агента с задачей, следит за его работой, отвечает ему и забирает результат — merge request, патч или архив — так же, как это делает консоль.

Что умеет API

Создать агента с задачей и рабочей копией: git-репозиторий (или ссылка на открытый PR/MR, который агент обновит), пустая папка со стартовым zip, S3 или папка Яндекс Диска. Можно выбрать модель, машину и лимит — по бюджету или по времени.
Вести разговор: писать агенту, передавать файлы прямо в его рабочую копию, прерывать текущий шаг.
Следить за работой: читать транскрипт или слушать поток событий в реальном времени — реплики агента, вызовы инструментов, их результаты и конец хода.
Управлять жизненным циклом: ставить на паузу с сохранением, будить, завершать с доставкой результата.
Забрать результат: ссылку на merge request, патч в формате git diff или zip с рабочей копией.
Наводить порядок: искать агентов, переименовывать и удалять их.

Агенты из API — те же самые агенты. Они видны в консоли, им можно написать из Telegram, и стоят они так же: машина поминутно, токены по ценам каталога.

Как это выглядит

Красная сборка — хороший первый пример. Шаг в CI, который срабатывает на падение, создаёт агента:

curl https://kodagent.ru/api/v1/agents \
  -H "Authorization: Bearer $KODAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_kind": "git",
    "source_url": "https://github.com/acme/api",
    "source_ref": "main",
    "source_token": "ghp_...",
    "prompt": "Сборка упала на test_refund_twice. Найди причину и почини, не трогая другие тесты.",
    "budget_credits": 200
  }'

В ответе — агент и его первый запуск. На нашем железе машина стартует за секунду, и в потоке событий почти сразу появляются первые строки:

data: {"seq":3,"kind":"assistant","payload":{"text":"Запущу тест и посмотрю, что именно падает."}}

data: {"seq":4,"kind":"tool_use","payload":{"name":"Bash","input":{"command":"pytest tests/test_refunds.py -x"}}}

Когда агент закончит ход, ему можно ответить через /messages или завершить работу через /stop. При завершении агент закоммитит изменения, запушит ветку kodagent/agent-<id> и откроет merge request, а ссылка на него появится в ответе API.

Полный справочник — в документации API: авторизация, все поля и статусы, формат событий, ошибки и готовый пример на Python.

Сценарии

Красная сборка. Как в примере выше: CI сам отдаёт падение агенту, а человек приходит уже к merge request с исправлением.

Агент в вашем продукте. Кнопка «Собрать отчёт» или «Сделать прототип» в вашем сервисе создаёт агента на пустой рабочей копии со стартовыми файлами. Агент работает, а ваш сервис забирает zip с результатом и отдаёт его пользователю. Поток событий показывает ход работы в вашем собственном интерфейсе.

Бот в мессенджере команды. Бот передаёт задачу агенту, показывает его вопросы людям и отправляет агенту их ответы. Всё это — через те же вызовы /messages и поток событий.

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

Если задачу нужно ставить уже существующему агенту и писать код не хочется, есть вебхуки в разделе Консоль → Автоматизация: URL, который превращает событие из CI или CRM в задачу.

Ключи: доступ только по явному разрешению

API принимает обычные API-ключи Kodagent, но только те, которым явно включён доступ к API агентов. Переключатель есть в разделе Консоль → API-ключи. Все существующие ключи остаются ключами только к моделям. Если такой ключ лежит в конфиге кодинг-агента на ноутбуке, запускать машины с ним не получится.

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

Такой ключ запускает машины и тратит кредиты, поэтому держите его на сервере, а не в браузере или мобильном приложении.

Деньги

Всё как в консоли. Машина оплачивается поминутно: при старте блок времени удерживается авансом, а неиспользованные минуты возвращаются на баланс. Токены списываются по ценам каталога. У каждого запуска есть бюджет и срок, и действуют оба потолка. Лимиты расходов ключа считают его собственные запросы к моделям, а агентов ограничивают их бюджеты — задавайте budget_credits под задачу. Актуальные цены — на странице тарифов.

Честные границы

Через API пока создаются одиночные агенты. Проекты и команды агентов собираются в консоли или в Telegram.
Одобрения решает человек. Если агент просит разрешения на рискованный шаг, ответ даётся в консоли или в Telegram, а не через API: решать за человека — не дело интеграции.
Мы пока не присылаем уведомления на ваш URL. О конце хода вы узнаёте из потока событий или опросом.
Слотов одновременных агентов у организации ограниченное число. Если все заняты, API ответит 409.

Как начать

Откройте Консоль → API-ключи, создайте ключ и включите «Доступ к API агентов».
Загляните в документацию API: там быстрый старт с curl и пример интеграции на Python.
Начните с небольшой задачи с понятным критерием готовности, например «почини этот упавший тест», и запустите её из скрипта. За несколько минут станет понятно, как выглядит результат и сколько он стоит.

Удачной разработки!

← Назад к блогу