--- title: "Agent API" id: "1697" type: "page" slug: "agent-api" published_at: "2026-09-04T07:20:53+00:00" modified_at: "2026-09-04T09:02:28+00:00" url: "https://pastukhov.com/agents/multiagent/docs/agent-api" markdown_url: "https://pastukhov.com/agents/multiagent/docs/agent-api.md" excerpt: "Agent API — это способ управлять MultiAgent без интерфейса. Другие программы и агенты получают доступ…" --- # Agent API [https://pastukhov.com/agents/multiagent/docs/agent-api.md](https://pastukhov.com/agents/multiagent/docs/agent-api.md) **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 — на английском языке. [← Оглавление документации](/agents/multiagent/docs)