Агенты > Pastukhov MultiAgent > Документация MultiAgent > Agent API

Agent API

Agent API — это способ управлять MultiAgent без интерфейса. Другие программы и агенты получают доступ к фабрикам, агентам, инструментам и продуктам по набору команд, закрытых ключом. То, что вы делаете кнопками в браузере, через API можно поручить автоматике: например, ваш ассистент сам создаёт фабрику, разворачивает нового агента и проверяет, что он работает. Набор команд повторяет возможности интерфейса, но безопаснее: секреты принимаются только «на запись», произвольных команд нет, а долгие операции запускаются по отработанной схеме «запустил — проверяй». Список доступных команд программа получает из самого API — отдельная документация не нужна.

Ключ и проверка доступа

Каждый запрос к /api/agent/ должен нести ключ в заголовке X-API-Key. Сам ключ не хранится: в переменной окружения MULTIAGENT_HASH лежит его «отпечаток» (SHA-256 хеш — короткая строка, по которой нельзя восстановить ключ). При каждом запросе сервер вычисляет отпечаток присланного ключа и сравнивает с сохранённым.

  • Переменная не задана — весь API отвечает 503, «Agent API is disabled»: API выключен целиком;
  • Неверный или отсутствующий ключ — 401 Unauthorized (попытка записывается в журнал с адресом клиента);
  • Поверхности раздельны — ключ интерфейса не открывает API, а API-ключ не открывает браузерные страницы.

Будьте внимательны к окончанию адреса: /api/agent/... — программный интерфейс, доступ по ключу; /api/agents/... — обычный интерфейс с входом по учётной записи.

Каталог GET /api/agent

Первый запрос, который стоит сделать, — к адресу GET /api/agent: он возвращает полный каталог команд. В нём описано, чем управляет MultiAgent, как устроена проверка ключа (что означают ошибки 503 и 401), базовые понятия (фабрика, агент, продукт), как протекают долгие операции и как передаются секреты, а также каждая команда: метод, адрес, поля запроса и форма ответа. Каталог собирается из кода, поэтому всегда актуален — тому, кто знает только адрес и ключ, отдельная документация не нужна.

Долгие операции: запустил — проверяй

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

За каждой долгой операцией стоит задача в общей очереди: работы одной фабрики выполняются по одной, чтобы не мешать друг другу. Пока очередь до задачи не дошла, запрос статуса отвечает status: "queued" («в очереди») и строк прогресса ещё нет — это нормальное состояние, а не ошибка. Дождитесь смены на running.

POST /api/agent/factories             # создали фабрику
→ 202 { "operationId": "op_123", "message": "..." }

GET /api/agent/operations/op_123         # пока задача ждёт очереди
→ { "operationId": "op_123", "status": "queued", "lines": [] }

GET /api/agent/operations/op_123         # задача выполняется
→ { "operationId": "op_123", "kind": "...", "status": "running",
    "lines": [{ "text": "...", "isError": false }], ... }

GET /api/agent/operations/op_123         # конечное состояние
→ { "operationId": "op_123", "status": "done", "lines": [...], ... }

Ответ на запрос статуса содержит lines — строки прогресса операции по порядку, а последняя строка называет исход. Записи операций живут в памяти и не вечно: неизвестный или истёкший номер операции отвечает 404 с подсказкой проверить текущее состояние ресурса. Так же проверяются операции, запущенные из браузера.

Секреты — только запись

Ни один ответ API не содержит значение секрета — паролей, приватных ключей, токенов. Они принимаются при создании и обновлении, хранятся зашифрованными и наружу выдаются только косвенные признаки: задан ли пароль (флаг hasPassword), есть ли приватный ключ (hasPrivateKey), имена дополнительных переменных, маскированные значения.

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

Только заранее определённые операции

Через API нельзя выполнить на фабрике произвольную команду — только заранее определённые действия MultiAgent: установить, очистить, запустить, остановить, развернуть. Ввод каждой операции ограничен идентификаторами, именами, портами и проверяемыми полями; ни одна команда не принимает скрипты или произвольную конфигурацию. Даже действия по удалению (удаление фабрики или контейнера с данными, очистка Docker) — это заранее определённые, хорошо очерченные операции. Такая защита означает: даже ошибка или сбой автоматического клиента не сможет выполнить ничего непредусмотренного.

Что можно делать через API

  • Основное — сам каталог команд, статус любой операции по её номеру (в том числе начатой из браузера) и версия сборки экземпляра, чтобы замечать обновления;
  • Фабрики — список со статусом связи, просмотр одной фабрики и её расхода, проверка установленных служб (docker, postgres, forgejo, rsync, nginx, домашняя страница, центральный вход), тест подключения по SSH, проверка с перечнем замечаний и действиями по исправлению, создание (подключение задаётся либо номером уже заведённой машины, либо полями адреса, порта, логина и секретов), изменение, удаление, а также длинные операции починки: установка Docker, проверка, создание папок и пользователя агента, очистка Docker, запуск остановленного Postgres, установка postgres/forgejo/резервного копирования, импорт найденных на машине агентов. Здесь же — состояние общей базы данных (установлена или только остановлена), список баз в её контейнере и полная переустановка в один вызов; ручная синхронизация входа в Forgejo с центральным входом; выбор репозитория сразу по всем фабрикам; готовность локальных серверов на подсистеме Windows (WSL); предварительный просмотр предстоящей передачи фабрики. Общие переменные фабрики отдаются только именами — значения уходят в одну сторону;
  • Nginx — публичный доступ фабрики: статус и установка Nginx, сертификаты (собственный, самоподписанный, запрос Let’s Encrypt — долгая операция с прогрессом), включение HTTPS-порта, продление сертификата и скачивание публичной цепочки, пользовательские маршруты (создание, изменение, удаление);
  • Авторизация — жизненный цикл центрального входа: проверка, установка, применение настроек и удаление с сохранением данных и секретов;
  • Домашняя страница — чтение состояния, установка и обновление статичной панели в корне фабрики;
  • Модели — каталог моделей MultiAgent (список, создание, изменение, удаление), загрузка модели на выбранных агентов — одноимённая запись агента заменяется, исход по каждому агенту, смена приватной переменной пересоздаёт контейнер агента — и импорт с агента (одноимённые записи каталога заменяются, сохраняя расписание и иконку); приватные переменные в ответах маскированы — наружу только признак «значение задано»;
  • Навыки — каталог навыков MultiAgent (список, чтение файлов, создание, изменение, удаление — копии на агентах остаются), загрузка навыка на выбранных агентов точной заменой одноимённой папки и импорт с агента с заменой при совпадении имени;
  • Аккаунты — список, создание, изменение и удаление аккаунтов у поставщиков моделей, чтение квоты (из временного хранилища или с новой проверкой у провайдера), история использования моделей по дням, вход в Codex по коду устройства и выход. Ключи и токены — только на запись;
  • Аналитика — вся отчётность по агентам на чтение, с теми же условиями, что и в браузере (один агент, метки, выбранный флот, даты), плюс запуск дозагрузки истории в ClickHouse и её статус;
  • Статистика аккаунтов — та же отчётность, но по аккаунтам поставщиков: баланс и квота во времени, разрезы по провайдерам и по аккаунтам, распределения, средние по часам и дням недели и последние снимки;
  • Лицензии — статус собственной лицензии MultiAgent и установка нового ключа; ключ — только на запись;
  • Лицензии агентов — пул лицензий агентов: список, создание, изменение, продление на срок, удаление и назначения — какие агенты её используют; выпуск нового ключа прямо на узле, когда на нём лежит закрытый ключ подписи. Ключ всегда маскирован, а занятую лицензию удалить нельзя — конфликт с числом ссылок;
  • Агенты — список с типом (обычный агент или продукт), слагом, портом, публичным адресом и состоянием контейнера; просмотр состояния (статус, журналы, статистика, конфигурация, проверка API); создание — порт подбирается сам, для продуктов — из каталога продуктов с переменными; жизненный цикл: развернуть, запустить, остановить, перезапустить, обновить, пересоздать, удалить. Здесь же — Git-обвязка и базы данных агентов: список репозиториев Forgejo фабрики (с учётом организации из поля «Компания»), создание репозитория и привязка его к агенту (или привязка существующего), проверка учётных данных внешней базы до создания агента, тест собственных учётных данных базы агента и чтение ссылок — что сейчас ссылается на агента (удобно перед удалением). Отдельной команды «скачать образ» нет — пересоздание само тянет свежий образ;
  • Чаты — прозрачный доступ к программному интерфейсу самого агента: прочитать список чатов, отправить сообщение, получить ответ — так же, как это делает браузер;
  • Инструменты — шаблоны инструментов (каталог и полное описание с переменными) и их установка на фабрику с проверкой переменных; у установленного инструмента можно посмотреть состояние, журналы и статистику, переключить публичность портов и защиту центральным входом, обновить образ и пересоздать контейнер;
  • Продукты — каталог продуктов на чтение, с описаниями переменных каждого продукта;
  • Перенос — приём полного набора записей одной фабрики от другого экземпляра MultiAgent: так принимающая сторона передачи забирает подключение, фабрику, агентов и продукты с их секретами, инструменты, маршруты и сертификаты;
  • Сессия — разовый код для входа в интерфейс без пароля (для случая, когда всё же нужен вход человека);
  • Решения — агент может передать оператору вопрос, уведомление или запрос на проверку (с оценкой стоимости и риска) и прочитать свои активные пункты. Действие, которое можно отменить и которое стоит меньше 500 долларов, одобряется само и в очередь не попадает (остаётся след в журнале); дорогое (от 5000 долларов) или необратимое становится блокирующим, остальное встаёт в обычную очередь. Повтор с тем же ключом увеличивает счётчик уже стоящего пункта, а не создаёт дубль.

Примеры вызовов

# Каталог — самоописывающаяся документация поверхности
curl -H "X-API-Key: my-key" https://multiagent.example.com/api/agent

# Список фабрик со статусом связи
curl -H "X-API-Key: my-key" https://multiagent.example.com/api/agent/factories

# Создать фабрику: подключение — либо номер уже заведённой машины,
# либо поля подключения целиком (server, username, password/privateKey, sshPort)
curl -X POST -H "X-API-Key: my-key" -H "Content-Type: application/json" \
  -d '{"name":"Prod","slug":"prod","serverId":3}' \
  https://multiagent.example.com/api/agent/factories
# либо: -d '{"name":"Prod","slug":"prod","server":"10.0.0.5","sshPort":22,"username":"root","password":"…"}'

# Создать агента и развернуть (202 + проверка статуса operations/{id})
curl -X POST -H "X-API-Key: my-key" -H "Content-Type: application/json" \
  -d '{"name":"bot","factoryId":3,"slug":"bot"}' \
  https://multiagent.example.com/api/agent/agents
curl -X POST https://multiagent.example.com/api/agent/agents/42/provision

# Проверки фабрики: 202, в операции структурированные результаты с действиями
curl -X POST -H "X-API-Key: my-key" https://multiagent.example.com/api/agent/factories/3/check
# опрос operations/{id} возвращает checks[]: код, статус, детали и действие исправления

# Модель: загрузить на выбранных агентов (замена одноимённой записи)
curl -X POST -H "X-API-Key: my-key" -H "Content-Type: application/json" \
  -d '{"agentIds":[3,4]}' \
  https://multiagent.example.com/api/agent/models/12/push

Формат ошибок единый — тело ответа всегда { error, message }. Неверные данные — 400 InvalidRequest; неизвестный ресурс — 404 NotFound; конфликты (например, удаление фабрики, на которую ссылаются агенты) — 409 Conflict с числом затронутых агентов; лицензионные ограничения создания — 403 с признаком истекшей лицензии; недоступная машина при удалённой проверке — 502 RemoteError с причиной. Сообщения API — на английском языке.

Agent API — не единственный машинный вход. Если нужны только цифры аналитики, есть язык запросов GraphQL по адресу /graphql: тот же отчёт, что и на экранах «Токены», «Стоимость», «Скорость» и «Чаты», только для чтения и со своим паролем — подробнее на странице Аналитика и выгрузки.

← Оглавление документации