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

Agent API

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

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

Каждый запрос к /api/agent/ должен нести ключ в заголовке X-API-Key. Сам ключ на сервере не хранится: в переменной окружения MULTIAGENT_API_KEY лежит его «отпечаток» (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, развёртывание агентов и инструментов — выполняются одинаково. Команда запуска сразу возвращает номер операции, а программа периодически спрашивает статус, пока не увидит «готово» или «сбой». Это как заказ в ресторане: вам не нужно ждать у плиты — вы получаете номер заказа и возвращаетесь, когда блюдо готово. Повторно запускать команду не нужно — операция уже идёт.

POST /api/agent/servers                 # создали сервер
→ 202 { "operationId": "op_123", "message": "..." }

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/резервного копирования, импорт найденных на сервере агентов;
  • Публичный доступ сервера — настройка HTTPS, центрального входа и домашней страницы через API, без интерфейса: статус и установка Nginx, сертификаты (собственный, самоподписанный, запрос Let’s Encrypt — долгая операция с прогрессом), включение HTTPS-порта, пользовательские маршруты (создание, изменение, удаление, защита за центральным входом), жизненный цикл центрального входа — установка, применение, удаление с сохранением данных и секретов — и домашняя страница: установка и обновление статичной панели в корне сервера;
  • Передача сервера и разовый вход — приём записей сервера от другого экземпляра MultiAgent (так работает передача управления) и выдача разового кода для входа в интерфейс без пароля — этим пользуется кнопка «Управление» на странице сервера;
  • Проверки сервера — запуск проверки возвращает структурированные результаты по каждой строке чек-листа (код, статус: пройдено/предупреждение/ошибка/пропущено, детали и действие исправления); действие запускает ту же одношаговую установку, что и кнопка «Проверить и исправить» в интерфейсе, поэтому весь цикл «проверь — исправь — перепроверь» выполним по API; проверки без предпосылок помечаются пропущенными и не считаются;
  • Агенты — список с типом (обычный агент или продукт), слагом, портом, публичным адресом и состоянием контейнера; просмотр состояния (статус, журналы, статистика, конфигурация, проверка API); создание — порт подбирается автоматически, для продуктов — из каталога продуктов с переменными; жизненный цикл: развернуть, запустить, остановить, перезапустить, пересоздать, удалить. Отдельной команды «скачать образ» нет — пересоздание само тянет свежий образ;
  • Git-обвязка и базы данных агентов — список репозиториев Forgejo сервера (с учётом организации из поля «Компания»), создание репозитория и привязка его к агенту (или привязка существующего), проверка учётных данных внешней базы данных до создания агента, тест собственных учётных данных базы агента и чтение ссылок — что сейчас ссылается на агента (удобно перед удалением);
  • Модели — каталог моделей MultiAgent (список, создание, изменение, удаление), загрузка модели на выбранных агентов — одноимённая запись агента заменяется, исход по каждому агенту, смена приватной переменной пересоздаёт контейнер агента — и импорт с агента (одноимённые записи каталога заменяются, сохраняя расписание и иконку); приватные переменные в ответах маскированы — наружу только признак «значение задано»;
  • Навыки — каталог навыков MultiAgent (список, чтение файлов, создание, изменение, удаление — копии на агентах остаются), загрузка навыка на выбранных агентов точной заменой одноимённой папки и импорт с агента с заменой при совпадении имени;
  • Лицензии — статус собственной лицензии MultiAgent и установка нового ключа; пул лицензий агентов: список, создание, изменение, удаление — ключ принимается только на запись и всегда маскирован, занятую лицензию удалить нельзя (конфликт с числом ссылок);
  • Инструменты и продукты — шаблоны инструментов (каталог и полное описание с переменными) и их установка на сервер с проверкой переменных; каталог продуктов доступен для чтения — с описаниями переменных.

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

# Каталог — самоописывающаяся документация поверхности
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/servers

# Создать агента и развернуть (202 + проверка статуса operations/{id})
curl -X POST -H "X-API-Key: my-key" -H "Content-Type: application/json" \
  -d '{"name":"bot","serverId":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/servers/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 — на английском языке.

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