ИИ‑агенты > 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, проверка, создание папок, очистка Docker, установка postgres/forgejo/резервного копирования, импорт найденных на сервере агентов;
  • Агенты — список с типом (обычный агент или продукт), слагом, портом, публичным адресом и состоянием контейнера; просмотр состояния (статус, журналы, статистика, конфигурация, проверка API); создание — порт подбирается автоматически, для продуктов — из каталога продуктов с переменными; жизненный цикл: развернуть, запустить, остановить, перезапустить, пересоздать, удалить. Отдельной команды «скачать образ» нет — пересоздание само тянет свежий образ;
  • Инструменты и продукты — шаблоны инструментов (каталог и полное описание с переменными) и их установка на сервер с проверкой переменных; каталог продуктов доступен для чтения — с описаниями переменных.

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

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

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

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