---
title: "Agent API"
id: "1697"
type: "page"
slug: "agent-api"
published_at: "2026-09-04T07:20:53+00:00"
modified_at: "2026-10-22T16:36:13+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_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`: тот же отчёт, что и на экранах «Токены», «Стоимость», «Скорость» и «Чаты», только для чтения и со своим паролем — подробнее на странице [Аналитика и выгрузки](/agents/multiagent/docs/analytics)
.

[← Оглавление документации](/agents/multiagent/docs)