ИИ‑агенты > Pastukhov Agent > Документация > MiniAgent

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 — чтение, правка и создание файлов, запуск команд, поиск и загрузка навыков;
  • Постоянные сессии — диалог сохраняется в формате JSONL и возобновляется после перезапуска;
  • Переключение модели и уровня размышлений на лету — прямо посреди диалога, ничего не теряя;
  • Автоматическое сжатие контекста — длинные разговоры не «забывают» начало;
  • Повторы при временных сбоях провайдера и защита от потери ответа;
  • Подсчёт токенов и стоимости — в чате и в аналитике;
  • Контекст проекта — сам читает CLAUDE.md/AGENTS.md (приоритет у CLAUDE.md) и сам находит навыки .claude/skills;
  • Интерактивные формы и кнопки (agent.form/agent.button) — прямо в системном промпте, без отдельных дополнений.

Примечание: передача изображений в чат пока не подключена — картинки при отправке игнорируются с предупреждением в логе.

Подключение

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 целиком.

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

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

ПолеТипДефолтЧто делает
loadClaudeMdbooltrueзагружает CLAUDE.md в контекст
loadAgentsMdbooltrueзагружает AGENTS.md в контекст
enabledToolsсписок имённет (включены все 11)белый список инструментов; пустой список — ошибка; несовместим с disabledTools
disabledToolsсписок имённет (все включены)денy-лист инструментов; несовместим с enabledTools
toolCallTimeoutint, сек300потолок одного вызова инструмента
maxOutputTokensint131072потолок выходных токенов запроса; перекрывает maxTokens модели
thinkingBudgetint65536бюджет размышлений для всех уровней мышления, кроме off; применяется на серверах anthropic
parallelBashThreadsint5сколько команд одного вызова parallel_bash исполняется одновременно
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. Оба списка 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_MDloadClaudeMd
MINI_PROFILE_LOAD_AGENTS_MDloadAgentsMd
MINI_PROFILE_ENABLED_TOOLSenabledTools (имена через запятую)
MINI_PROFILE_DISABLED_TOOLSdisabledTools (имена через запятую)
MINI_PROFILE_TOOL_CALL_TIMEOUTtoolCallTimeout
MINI_PROFILE_MAX_OUTPUT_TOKENSmaxOutputTokens
MINI_PROFILE_THINKING_BUDGETthinkingBudget
MINI_PROFILE_PARALLEL_BASH_THREADSparallelBashThreads
MINI_PROFILE_SYSTEM_PROMPTsystemPrompt
MINI_PROFILE_SESSION_HEADERsessionHeader

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

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

docker run -e MINI_PROFILE_TOOL_CALL_TIMEOUT=120 \
           -e MINI_PROFILE_DISABLED_TOOLS=bash \
           pastukhov/agent

Инструмент 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 не изменилось.

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

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

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

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

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

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

profiles:
  safe:
    disabledTools:
      - bash
    toolCallTimeout: 60

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

  • Настройки — карточка MiniAgent и хаб настроек;
  • Модели — переменная AGENT_BACKEND и выбор профиля моделью;
  • Навыки — навыки в чате и инструмент load_skill.

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

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