MiniAgent

MiniAgent — встроенный кодинг-агент: полностью самостоятельная «обвязка», вшитая прямо в Pastukhov Agent (библиотека на C#, минималистичный агент в духе Pi, переписанный с нуля). Ей не нужна внешняя программа и ей нечего устанавливать — Pastukhov Agent и MiniAgent представляют собой единое целое и полностью самодостаточны «из коробки».

MiniAgent — часть системы обвязок Pastukhov Agent и выбирается переменной AGENT_BACKEND=mini. Общий обзор обвязок — на странице Обвязки.

Почему это важно для бизнеса

Обычные обвязки — это сторонние программы, которые скачиваются и устанавливаются через менеджер пакетов. MiniAgent устроена иначе: она живёт внутри самого Pastukhov Agent, поэтому:

Независимость от сторонних разработчиков. Работа агента не зависит от чужих проектов и их обновлений — движок всегда под рукой у сервера.
Безопасность поставки. Никакой установки пакетов из сторонних источников — исчезает сам риск получения скомпрометированного установочного пакета.
Самодостаточность «из коробки». MiniAgent уже внутри продукта: нечего скачивать, устанавливать и обновлять отдельно.
Всё на вашем сервере. Агент работает там же, где и Pastukhov Agent: данные не покидают вашу инфраструктуру.

Возможности

Это полноценный агент со всем, что нужно для реальной работы:

Инструменты read, write, edit, bash, parallel_bash, grep, find, ls, glob, load_skill, todo_write, agent и фоновые задачи agent_start, agent_check, agent_stop — чтение, правка и создание файлов, запуск команд, поиск, загрузка навыков и запуск подагентов;
Постоянные сессии — диалог сохраняется в формате JSONL и возобновляется после перезапуска;
Переключение модели и уровня размышлений на лету — прямо посреди диалога, ничего не теряя;
Автоматическое сжатие контекста — длинные разговоры не «забывают» начало;
Повторы при временных сбоях провайдера и защита от потери ответа — пауза между попытками и их число настраиваются (подробнее ниже);
Подсчёт токенов и стоимости — в чате и в аналитике;
Контекст проекта — сам читает CLAUDE.md/AGENTS.md (приоритет у CLAUDE.md) и сам находит навыки .claude/skills;
Интерактивные формы и кнопки (agent.form/agent.button) — прямо в системном промпте, без отдельных дополнений;
Чтение картинок — инструмент read прикладывает файл-изображение к запросу (подробности в примечании ниже);
Внешние инструменты и правила — MiniAgent сам подключает MCP-серверы из mcp.yml и применяет хуки из hooks.yml: в мини-чатах они работают так же, как у командных агентов;
Подагенты — инструмент agent запускает вложенный сеанс с собственным контекстом, видимый дочерним чатом: несколько вызовов в одном ответе работают одновременно, а рядом есть фоновые задачи, чей итог приходит в текущий ход сам (подробнее ниже).

Примечание: отправка изображений в чат пока не подключена — приложенные к сообщению картинки игнорируются с предупреждением в журнале. При этом агент сам читает картинки с диска инструментом read: на моделях, которым разрешён ввод изображений, файл прикладывается к запросу (jpg, png, gif, webp, bmp до 5 МБ), а на текстовых моделях возвращается понятная ошибка. Файл больше предела отклоняется с подсказкой уменьшить его командой.

Подключение

MiniAgent выбирается переменной AGENT_BACKEND=mini. Проще всего создать модель из готового шаблона провайдера, где обвязка MiniAgent уже есть: Anthropic, DeepSeek, z.ai, BigModel, OpenRouter, xAI, MiniMax, Moonshot, OpenAI, OpenCode Go/Zen. Шаблон сам подставит обвязку и параметры подключения:

MINI_BASE_URL — адрес провайдера;
MINI_API — формат протокола: anthropic-messages или openai-completions;
MINI_AUTH — тип авторизации: api-key или bearer;
MINI_API_KEY — ключ доступа.

Модель задаётся в формате «провайдер/модель:мышление», например MODEL=anthropic/claude-sonnet-5:medium. Суффикс :thinking задаёт уровень размышлений: off, minimal, low, medium, high. Модель, которой нет в шаблоне, соберётся автоматически по параметрам выше; при наличии файла ~/.mini/models.json (формат, совместимый с Pi) приоритет у него. Если модель не задана вовсе, используется deepseek/deepseek-v4-flash. Провайдера по умолчанию можно указать переменной MINI_PROVIDER — она используется, когда в имени модели нет префикса «провайдер/».

Данные

Данные MiniAgent хранятся в папке ~/.mini (переопределяется переменной MINI_AGENT_DIR):

models.json — конфигурация моделей;
agent-sessions — сессии в формате JSONL;
skills — дополнительные навыки;
CLAUDE.md — глобальный контекст.

Профили MiniAgent

Профиль — именованный набор настроек встроенного агента: какие контекстные файлы загружать, какими инструментами разрешено пользоваться, как долго может выполняться один вызов, какой токеновый потолок стоит у запросов и сколько подагентов разрешено запускать разом. Профили позволяют держать несколько режимов работы одного проекта: «безопасный» без bash для чувствительных репозиториев, «черновой» с большим таймаутом для тяжёлых задач, «только чтение» для ревью — и переключаться между ними просто сменой модели.

Профили живут в файле miniagent.yml в папке бренда проекта (.xedant/ или .pastukhov/). Корневая карта profiles: — ключом служит имя профиля, значением — его настройки:

# miniagent.yml
profiles:
  safe:                       # безопасный режим: без bash, короткий таймаут
    disabledTools:
      - bash
    toolCallTimeout: 60
    loadAgentsMd: false

  readonly:                   # только чтение: разрешены лишь поисковые инструменты
    enabledTools:
      - read
      - grep
      - find
      - glob
      - ls

Модель выбирает профиль суффиксом mini:имя в переменной AGENT_BACKEND конфигурации модели на странице Модели — например, AGENT_BACKEND=mini:safe. Имя профиля приводится к нижнему регистру и ищется без учёта регистра; легаси-псевдоним mini-agent:safe тоже работает. Обычное AGENT_BACKEND=mini без суффикса, пустой суффикс или несуществующее имя дают встроенные настройки по умолчанию — об отсутствующем профиле записывается предупреждение в журнал. Суффикс с двоеточием понимает только обвязка MiniAgent, остальные обвязки принимают AGENT_BACKEND целиком.

Настройки профиля

Каждое поле профиля необязательно: пропущенное поле, пустой профиль {} или отсутствующий файл означают встроенные значения по умолчанию.

Поле	Тип	Дефолт	Что делает
`loadClaudeMd`	bool	`true`	загружает `CLAUDE.md` в контекст
`loadAgentsMd`	bool	`true`	загружает `AGENTS.md` в контекст
`enabledTools`	список имён	нет (включены все 11)	белый список инструментов; пустой список — ошибка; несовместим с `disabledTools`
`disabledTools`	список имён	нет (все включены)	денy-лист инструментов; несовместим с `enabledTools`
`toolCallTimeout`	int, сек	`300`	потолок одного вызова инструмента
`maxOutputTokens`	int	`131072`	потолок выходных токенов запроса; перекрывает `maxTokens` модели
`thinkingBudget`	int	`65536`	бюджет размышлений для всех уровней мышления, кроме `off`; применяется на серверах anthropic
`parallelBashThreads`	int	`5`	сколько команд одного вызова `parallel_bash` исполняется одновременно
`maxParallelAgents`	int	`4`	сколько подагентов одного чата работают одновременно; остальные ждут очереди
`systemPrompt`	строка	встроенный	заменяет встроенный базовый системный промпт; пустой — тоже встроенный
`sessionHeader`	строка	нет (`X-Agent-Session`, на opencode — `X-Opencode-Session`)	имя HTTP-заголовка, в котором каждый запрос к провайдеру несёт идентификатор сессии; запись `headers` в models.json с тем же именем имеет приоритет

Профиль управляет ровно 11 встроенными инструментами: read, bash, parallel_bash, edit, write, grep, find, glob, ls, load_skill, todo_write. Инструменты agent, agent_start, agent_check и agent_stop стоят особняком: они добавляются каждому основному чату всегда, и списки профиля их не фильтруют — ни включить, ни отключить их через профиль нельзя. Оба списка enabledTools и disabledTools в одном профиле — ошибка (одновременно и в yml, и в переменных окружения): разрешать и запрещать один и тот же инструмент бессмысленно. Пустой enabledTools отклоняется — он оставил бы профиль вообще без инструментов, а пустой disabledTools даёт только предупреждение.

Приоритет каждой настройки: переменная окружения > профиль > встроенное значение по умолчанию. Профиль накладывается поверх значений по умолчанию, а переменная — поверх профиля.

Заголовок сессии. Каждый запрос к провайдеру несёт идентификатор сессии в HTTP-заголовке — принимающий провайдер может различать чаты MiniAgent: группировать трафик, ограничивать частоту запросов или вести временное хранилище по сессии, не разбирая переписку. По умолчанию заголовок называется X-Agent-Session, на провайдерах opencode (имя провайдера начинается с opencode или адрес на opencode.ai) — X-Opencode-Session. Имя меняется полем sessionHeader профиля или переменной MINI_PROFILE_SESSION_HEADER; явная запись headers в models.json с тем же именем главнее автоматической отправки. У ключа sessionHeader нет редактора в диалоге настроек — его вписывают вручную в miniagent.yml или задают переменной, диалог передаёт вручную заданное значение без изменений. Запрос, отправленный до появления идентификатора сессии, заголовка не несёт.

Переменные окружения

Любую настройку профиля можно переопределить на уровне процесса переменной MINI_PROFILE_* — она применяется поверх выбранного профиля (или значений по умолчанию, если профиль не задан):

Переменная	Переопределяет
`MINI_PROFILE_LOAD_CLAUDE_MD`	`loadClaudeMd`
`MINI_PROFILE_LOAD_AGENTS_MD`	`loadAgentsMd`
`MINI_PROFILE_ENABLED_TOOLS`	`enabledTools` (имена через запятую)
`MINI_PROFILE_DISABLED_TOOLS`	`disabledTools` (имена через запятую)
`MINI_PROFILE_TOOL_CALL_TIMEOUT`	`toolCallTimeout`
`MINI_PROFILE_MAX_OUTPUT_TOKENS`	`maxOutputTokens`
`MINI_PROFILE_THINKING_BUDGET`	`thinkingBudget`
`MINI_PROFILE_PARALLEL_BASH_THREADS`	`parallelBashThreads`
`MINI_PROFILE_MAX_PARALLEL_AGENTS`	`maxParallelAgents`
`MINI_PROFILE_SYSTEM_PROMPT`	`systemPrompt`
`MINI_PROFILE_SESSION_HEADER`	`sessionHeader`

Пустое значение переменной считается не заданным — настройка берётся из профиля или значения по умолчанию, так что «очистить» переопределение можно пустой строкой. Обе list-переменные одновременно (MINI_PROFILE_ENABLED_TOOLS и MINI_PROFILE_DISABLED_TOOLS) — жёсткая ошибка, как и неразбираемое значение (не true/false, не положительное число): сессия не создастся, а в ошибке будет названа сама переменная.

Пример — таймаут вызова 120 секунд и запрет bash для всех чатов: задайте переменные MINI_PROFILE_TOOL_CALL_TIMEOUT=120 и MINI_PROFILE_DISABLED_TOOLS=bash.

MiniAgent, как и остальные обвязки, уважает сетевые переменные HTTP_PROXY, HTTPS_PROXY и NO_PROXY: если сервер выходит в интернет через прокси, запросы к провайдеру пойдут через него, а адреса из NO_PROXY — напрямую. Подробнее — на странице Модели.

Инструмент parallel_bash

parallel_bash — инструмент MiniAgent для запуска нескольких независимых команд одним вызовом. Модель сама решает, какие команды не зависят друг от друга (этот контракт независимости зафиксирован в описании инструмента), и объединяет их в один вызов:

parallel bash:
  - git status --short
  - ls pages/ | wc -l
  - df -h /project

Команды исполняются конкурентно: parallelBashThreads (по умолчанию 5) ограничивает, сколько команд выполняется одновременно, остальные ждут в очереди. Вызов завершается после ответа всех команд, а результат возвращает упорядоченные секции [i] command — по одной на команду, в порядке ввода, что позволяет агенту сопоставить каждый вывод со своей командой. Тривиальная разница с bash: bash исполняет одну команду, parallel_bash — пакет; оба работают на общем ядре ShellCommand, и поведение bash не изменилось.

Подагенты

Инструмент agent позволяет модели запустить отдельного подагента — вложенный сеанс со своим контекстом и своим журналом. Это тот же приём, что «подзадачи» у командных агентов: большая задача разбивается на части, и каждая часть работает в чистом контексте, не засоряя основную беседу.

Вызов несёт описание задачи и подробное указание — как у инструмента подзадач командного агента;
вложенный запуск виден отдельным дочерним чатом, привязанным к родительскому: его сообщения, расход и стоимость появляются в реальном времени, а в родительском чате растёт сводка по подагентам;
итоговый ответ подагента (усечённый до общих пределов вывода) возвращается родителю как результат инструмента;
подагент работает без навыка чата, без MCP-серверов, без хуков и без самого инструмента agent — запустить своего подагента он не может;
остановка родительского чата доходит и до вложенного запуска, а в дочернем чате остаётся всё, что тот успел сделать.

Несколько подагентов сразу

Если в одном ответе модели вызовов agent несколько, они стартуют одновременно: карточки всех вызовов появляются сразу, а результаты возвращаются в порядке вызовов. Сколько подагентов одного чата работает разом, задаёт настройка профиля maxParallelAgents (по умолчанию 4): лишние вызовы встают в очередь и начинают работу, как только освободится место. Предел один на весь чат — очередь у обычных и у фоновых задач общая.

Фоновые задачи

Для долгой работы есть три отдельных инструмента. agent_start ставит задачу в очередь и сразу отдаёт её номер. agent_check сообщает состояние задачи, а после завершения — её итоговый ответ или текст ошибки. agent_stop останавливает работающую задачу или отменяет ту, что ещё ждёт своей очереди.

Итог приходит сам. Опрашивать ничего не нужно: завершившаяся задача сама приносит результат в текущий ход, и он виден на строке вызова agent_start — как раскрываемый результат у обычного вызова. Пока у чата есть незавершённые фоновые задачи, ход не закрывается;
Короткая подпись вместо номера. В чате фоновые вызовы показаны понятной строкой — «Запускаю агента …», «Проверяю агента …», «Останавливаю агента …» — с названием задачи, которое придумала модель;
Результат не теряется. Итог задачи хранится на сервере: к нему можно вернуться по тому же номеру — и в другом ходе, и после перезапуска приложения. Задачи, оборванные остановкой сервера, при следующем запуске закрываются с пометкой об остановке;
Остановка чата снимает всё. Если остановить родительский чат, все его фоновые задачи завершаются: работающие останавливаются, ждущие отменяются. В дочернем чате остаётся всё, что успел сделать подагент, и пометка об остановке; у отменённой ждущей задачи дочернего чата нет вовсе.

MCP-серверы

MiniAgent сам подключает MCP-серверы, включённые в файле mcp.yml, — командная строка Claude Code для этого не нужна. Поддерживаются те же три способа подключения: локальные процессы (stdio), удалённые серверы по http и устаревающий sse.

Серверы подключаются не при запуске, а при первом сообщении чата. Выключенные записи пропускаются. Если сервер не поднялся или не ответил, чат продолжает работать, а в журнал идёт предупреждение с именем сервера: один неисправный сервер не тянет за собой остальные и не мешает разговору. В командах, аргументах, переменных окружения, адресах и заголовках раскрываются $ИМЯ, ${ИМЯ} и ${ИМЯ:-значение-по-умолчанию} — сначала по переменным чата, затем по окружению; незаданная переменная остаётся как есть с предупреждением. При остановке чата подключения закрываются, а локальные процессы серверов гасятся, поэтому остановка не ждёт их выхода.

Как завести серверы и что лежит в mcp.yml — на странице MCP-серверы.

Хуки

Правила из hooks.yml действуют и в мини-чатах: запрет инструмента, проверка перед его вызовом, действия по событиям разговора. Один и тот же каталог передаётся и командным агентам, и MiniAgent, поэтому правила не нужно заводить дважды.

Список событий, запрещающие правила и предел времени на выполнение — на странице Хуки.

Диалог профилей в настройках

Диалог открывается с карточки «MiniAgent» группы Configuration в центре настроек (шестерёнка в шапке) — подробнее о хабе на странице Настройки. Диалог редактирует тот же miniagent.yml, что и текстовый YAML-редактор, но как форму:

Список профилей — создание, переименование и удаление. Имя подчиняется маске ^[a-z0-9][a-z0-9_-]*$: строчная буква или цифра, дальше строчные буквы, цифры, дефисы и подчёркивания — оно же становится суффиксом mini:имя;
Редактор профиля — переключатели loadClaudeMd/loadAgentsMd, переключатели инструментов с итогом «N of M tools enabled» (меняют disabledTools), числовые поля с подсказками значений по умолчанию и редактор системного промпта с предпросмотром встроенного. Среди числовых полей есть «Параллельных агентов» — сколько подагентов одного чата запускать одновременно (по умолчанию 4, подсказка «Субагенты одного чата, запущенные одновременно; лишние ждут очереди»); ноль и отрицательное число сохранить нельзя. Кнопка Reset to default очищает текст промпта — встроенный берётся заново при каждом обновлении приложения, а не копируется;
Сводка встроенных значений по умолчанию — показана рядом со списком;
Защита от конфликтов — каждое сохранение проходит проверку контрольной суммы (md5): если файл успел измениться (правка в другом клиенте, текстовом редакторе или вкладке Project Settings), сервер отвечает 409 с предложением перезагрузить диалог — правки не затираются молча;
Та же валидация, что у YAML — и сохранение из формы, и правка текстом проходят одни и те же правила (имена профилей, взаимоисключение списков, диапазоны чисел) и дают одинаковые ошибки; валидатор работает как псевдо-сборка.

Настройки фиксируются при создании сессии: живой чат работает с тем профилем, с которым был создан, а правки применяются к новым сессиям — переключение профиля или модели пересоздаёт сессию. Ещё одна тонкость: если в профиле отключён инструмент load_skill, из системного промпта пропадает строка «Start by loading the skill» — требовать загрузку навыка инструментом, которого нет, бессмысленно.

Настройки повтора

Поставщик ИИ иногда отвечает не сразу: сервис перегружен, обращений слишком много, соединение оборвалось. Вместо того чтобы сразу закончить ход ошибкой, MiniAgent повторяет запрос — и часто ответ приходит уже на повторе. Сколько ждать между попытками и сколько попыток делать, вы задаёте сами: для этого в центре настроек есть карточка «Повторить» в группе «Конфигурация» (шестерёнка в шапке). Подробнее о хабе — на странице Настройки.

Карточка открывает диалог «Настройки повтора» с двумя полями:

Интервал повтора — сколько секунд ждать перед повтором неудачного запроса, по умолчанию 60 секунд;
Максимальное число попыток — сколько всего раз запрос отправляется (первый запрос плюс повторы), прежде чем ошибка завершит ход, по умолчанию 10. Допустимо только целое число больше нуля;

Пауза всегда одна и та же — с каждой попыткой она не растёт. Пустое поле означает «вернуть значение по умолчанию». Внизу диалога видно, где лежит файл настроек.

Повторяются только временные сбои: перегруженный сервис, ограничение частоты обращений, ответы 400, 429 и 5xx, обрывы соединения. А вот случаи, которые от повтора не изменятся, — исчерпанные лимиты и кредиты аккаунта — чат показывает сразу, не дожидаясь остальных попыток (при значениях по умолчанию это сэкономило бы до девяти минут ожидания).

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

Значения хранятся в файле retry.yml в папке бренда проекта (.xedant/ или .pastukhov/):

retryIntervalSeconds: 60
maxAttempts: 10

Тот же файл можно править текстом во вкладке настроек проекта и любым редактором — изменение подхватывается по ходу работы. Если файл повреждён, диалог покажет значения по умолчанию и пояснит, что сохранение заменит испорченный файл. Если файл правили в другом окне или текстом, диалог предупредит: «retry.yml изменён вне этого диалога. Ваши правки не сохранены.» — с кнопкой «Перезагрузить». Настройки применяются к новым сессиям: активный чат дорабатывает с той политикой, с которой был создан, а битый файл чаты не ломает — работают значения по умолчанию. Файл проверяется и при сборке: неизвестные ключи и число меньше единицы будут найдены, как у остальных файлов настроек.

Практический пример

Профиль «safe» — bash выключен, таймаут вызова 60 секунд. Создайте его в диалоге: Настройки → Configuration → MiniAgent → «Добавить профиль», имя safe, выключите переключатель bash и поставьте toolCallTimeout: 60, сохраните. Эквивалентный файл:

profiles:
  safe:
    disabledTools:
      - bash
    toolCallTimeout: 60

Теперь назначьте его модели: в мастере моделей на странице Модели задайте переменную AGENT_BACKEND=mini:safe (в yml — строка в списке variables:). Чаты на этой модели будут работать без запуска shell-команд и ограничат каждый вызов инструмента 60 секундами — всё остальное останется встроенным.

MCP-серверы — внешние инструменты и источники данных, которые MiniAgent подключает сам;
Хуки — правила запрета и выполнения, общие для командных агентов и мини-чатов;
Настройки — карточка MiniAgent и хаб настроек;
Модели — переменная AGENT_BACKEND, выбор профиля моделью и признак ввода изображений;
Навыки — навыки в чате и инструмент load_skill.

← Назад: Обвязки

Далее: Советы и устранение проблем →