Зачем сисадмину ИИ-агент: реальный опыт работы с pi

Статья для тех, кто живёт в терминале, пишет Ansible и устал копировать конфиги в окно браузера. Без картинок — только текст, код и честный опыт.

Вместо введения

Ночная смена. На мониторинге краснеет алерт — что-то опять не так на одном из серверов. Ты открываешь терминал, листаешь логи, лезешь в конфиги, пытаешься вспомнить, как именно три года назад настраивал этот сервис, грепаешь историю bash в поисках той самой команды… Знакомая картина?

Сегодня первый порыв — спросить ChatGPT. Он подскажет, где копать. Но давайте честно: он работает медленно и односторонне. Ты копируешь ему кусок конфига, он советует, ты идёшь применять, возвращаешься с результатом, он советует снова. Он не видит твои файлы, не правит inventory, не прогонит playbook и не перечитает логи после рестарта. Он — советник по переписке, а тебе нужен напарник в машинном зале.

Мне нужен был кто-то (или что-то), кто работает прямо в моём терминале, с моими файлами, под моим контролем. Но при этом — кто не выйдет за рамки дозволенного и не наломает дров на проде. Так я пришёл к агентам, а конкретно — к опенсорсному pi.

Эта статья — не обзор фич и не реклама. Это рассказ о том, как агент вписался в реальную работу инфраструктурного инженера: от написания Ansible-ролей до документации и настройки самого себя. С кодом, граблями и честными выводами.

Что такое агент (и чем он не чат-бот)

Если вы пользовались ChatGPT или Claude в браузере — это чат-бот. Вы пишете, он отвечает. Агент — зверь другой породы: у него есть инструменты. Он может читать ваши файлы, выполнять команды, править конфиги, искать в сети, опрашивать language-сервер — и всё это в цикле «подумал → сделал → увидел результат → подумал снова».

Для сисадмина в агенте важны две вещи. Первая — он работает в вашей среде: ваш терминал, ваши файлы, ваши хосты, доступные через SSH. Вторая — он опенсорсный и локальный. Ваши конфиги, inventory, пароли от vault не обязаны уезжать на чужой SaaS. Вы расширяете агент под свою инфраструктуру, а не подгоняете инфраструктуру под чужие предположения. Вендор-лока нет: агент — это инструмент, которым владеете вы.

Знакомство с pi

Тут я мог бы перечислить фичи, но не буду. Главное про pi — это пластилин в руках инженера.

На рынке сейчас хватает готовых «агентов из коробки»: мощных, обвешанных всем сразу, со своим мнением о том, как вам работать. Берёшь — и сразу получаешь конвейер, который что-то делает. Платите за это контролем над процессом: вы подстраиваетесь под инструмент, а не он под вас.

pi (github.com/earendil-works/pi-coding-agent, лицензия MIT) идёт другим путём. Это намеренно минималистичный агент: ядро, которое умеет думать и действовать в терминале, — и почти ничего больше. Всё остальное — расширения, скиллы, языковые серверы, субагенты — вы добавляете сами, под свои задачи. pi не навязывает вам чужой опыт; он готов к любому опыту, который вы в него вложите. За это приходится платить временем: чтобы агент стал «вашим», его нужно настроить.

И здесь главное: расширять возможности агента — это, как правило, дело рук самого агента. Не обязательно лезть в документацию и писать расширение на TypeScript с нуля (хотя можно). Чаще вы просто просите: «мне нужен учёт расходов — напиши расширение», «хочу, чтобы ты видел правки, которые я вношу в файлах снаружи — сделай», «подключи language-сервер для Ansible». Агент либо пишет расширение сам, либо находит готовое и ставит. Вы ставите задачу — он расширяет себя под неё.

Поэтому pi — это не продукт с фиксированным набором возможностей, а процесс, в котором агент и инженер вместе выстраивают инструмент под конкретную инфраструктуру. Работает он с любым OpenAI-compatible провайдером — российский шлюз, self-hosted через vLLM/Ollama, что угодно под вашу юрисдикцию. Весь конфиг живёт в ~/.pi/, и я держу его в Git: переезд на новую машину — клонировал репо, поставил пакеты, готово. Секреты — вне Git.

Главный кейс: Ansible-роли, которые читают и люди, и агенты

Это ядро моего опыта. Сейчас построение и управление инфраструктурой как кодом стало простым как никогда. Не нужно долго сидеть и мучаться, чтобы написать одну автоматизацию для трёх-пяти серверов, — можно попросить агента. Причём сам артефакт, сама автоматизация остаётся, и её можно использовать и улучшать в будущем. Здесь ещё заметнее раскрывается Ansible: теперь не нужно долго изучать этот инструмент — можно учиться ему и сразу применять вместе с агентом.

Идея, которую я хочу донести: хорошо написанная IaC-роль — это контракт, понятный и коллеге, и следующему ИИ-агенту.

От плана к роли

Всё начинается с PLAN.md — короткого текстового описания того, что мы хотим получить. Не с кода, а с намерения. Дальше агент разворачивает стандартную структуру роли:

roles/nginx/├── defaults/main.yml    # параметры по умолчанию — публичный API роли├── tasks/main.yml       # что делаем├── handlers/main.yml    # реакции на notify (рестарт, reload)└── vars/main.yml        # внутренние переменные

Что агент делает реально и хорошо:

• Генерирует каркас роли и не забывает ни про defaults, ни про handlers — то, что люди в спешке часто пропускают.

• Пишет tasks с идемпотентностью. Агент по умолчанию добавляет creates: к command, state: present к модулям пакетов, разделяет установку и конфигурацию. Роль можно прогонять сто раз — состояние не разъедется.

• Добавляет валидацию в handler. Перед рестартом сервиса — проверка синтаксиса конфига: nginx -t, named-checkconf, у sing-box — sing-box check. Если конфиг кривой, сервис не упадёт, а плейбук упадёт громко и по делу.

AGENTS.md — память проекта

Главный приём, ради которого стоит читать этот раздел. В корне каждого репозитория лежит AGENTS.md — контекст проекта для ассистента. Там зафиксировано: что уже сделано, какие грабли пойманы, где лежат секреты (vault), какие архитектурные решения устарели. Файл добавлен в .gitignore — это не часть поставки, это рабочая память.

Агент читает AGENTS.md одной из первых команд. Мне не нужно каждый раз объяснять: «у нас тут такое-то окружение, вот такие хосты, не трогай вот это». Контекст уже на месте. И что важно — агент сам его обновляет по ходу работы: развернули новую роль, поймали баг, сменили подход — в AGENTS.md появилась запись с датой.

Это и есть тот самый «контракт». Следующий инженер, который придёт в проект, прочитает AGENTS.md и PLAN.md — и вникнет без онбординга. Следующий агент — тоже. Роль, написанная с агентом, получается самодокументируемой: структура чистая, defaults описывают публичный API, handlers валидируют, а AGENTS.md хранит «почему».

LSP прямо в агенте

Через pi-lsp к агенту подключён ansible-language-server. Конфиг — простая декларация в JSON: по каким файлам (playbooks, tasks, handlers), какие root-маркеры (ansible.cfg, galaxy.yml, .ansible-lint) определяют корень проекта. После каждого edit агент отправляет файл серверу и получает диагностику — ansible-lint ругается на command без creates, на mode восьмеричной записью, на отсутствующий name у таски.

Цикл правки сокращается катастрофически. Раньше: написал роль → запустил плейбук → упало → прочитал ошибку → исправил. Теперь: агент пишет роль → LSP подсвечивает проблемы тут же → агент правит → запускает ansible-playbook --check. Ошибки ловятся до того, как вообще дойдут до сервера.

IaC-инфраструктура: агент на каждом этапе

Изменение конфигурации в Linux-инфраструктуре ещё никогда не было таким простым и централизованным: готовим задачу, обозначаем план, агент пишет роль Ansible, включаем её в плейбук и запускаем на нужных серверах или пользовательских АРМ. Любые задачи, которые раньше требовали большого количества времени, теперь требуют большой внимательности.

Нет, агент не работает за вас, не занимает ваше место — он помогает ускорить вашу работу с множеством машин автоматизированно.

С чего начать

С разработки глобального плана и принципов написания Ansible ролей и коллекций, Terraform-стейтов, Kubernetes-манифестов и HELM-чартов. С организации совместного Git-репозитория с AGENTS.md для понимания между инженерами и агентами. С написания конечных автоматизаций с актуальной документацией, понятной и людям, и агентам. С использования инструментов, облегчающих поиск по информации для агентов, — это экономит токены.

Жизненный цикл

Инфраструктура живёт по циклу:

Планирование → Разработка → Тестирование → Документирование → Применение → Поддержка и улучшение

Агент вписан на каждом этапе — от разработки базовых принципов и обслуживания архитектуры до её улучшения, развития и автоматизации процессов. CI гоняет ansible-lint, Makefile хранит целевые команды (make roles, make deploy), секреты лежат в vault. Повторяемость и воспроизводимость окружений перестаёт быть мечтой: одно и то же состояние разворачивается на новом железе за один прогон плейбука.

Конечная цель

Замкнуть агентов на самих себя — чтобы они строили архитектуру, развивали её, описывали, тестировали и улучшали. Инженер при этом — не наблюдатель и не жертва автоматизации, а человек, который обучается вместе с агентами и развивает инфраструктуру. Вы задаёте направление и принципы, агент берёт на себя исполнение и рутину, вы контролируете результат. Роль инженера смещается с «пишу YAML руками» на «проектирую систему и ревьюю то, что нагенерировано».

Кейс: агент-документатор

Документация всегда была важна. И всегда была рутиной, до которой руки доходят последними. С агентом эта рутина становится чужой заботой.

В моих проектах живёт несколько документов, которые агент поддерживает параллельно работе:

• README — актуальное описание архитектуры, ролей, команд. Не «написал однажды при создании репо», а живой документ: поменяли подход — README обновился в той же сессии.

• PLAN.md — план с явными отметками «реализовано», «устарело», «отложено». Когда архитектура меняется, план не врёт: прямо в шапке предупреждение, что такой-то раздел описывает прежнюю схему.

• AGENTS.md — уже упомянутая хронология сессий: что сделано, где грабли, куда не лезть.

Раньше документация была рутиной, теперь этой рутиной занимается агент, который выполняет эту работу за пять минут. А субагенты делают это параллельно — пока основной агент доделывает роль, дочерний docs-writer на дешёвой модели переписывает README. Документация перестаёт быть «тем, что пишут потом», и ведётся синхронно с кодом.

Для отчётности и спецификаций из офисных форматов есть скиллы docx и pdf — из репозитория anthropics/skills. Агент умеет собрать Word-документ с оглавлением и колонтитулами, прочитать чужой PDF, вытащить таблицу, склеить несколько PDF в один. Задача «оформи это в виде документа» перестаёт быть поводом отложить на вечер.

Кейс: агент настраивает сам себя

Здесь самое интересное. Любой аспект агента можно переписать под свои задачи — достаточно лишь попросить, чтобы именно он это и сделал. pi — конструктор, и агента можно натравить на него самого.

Собственное расширение

Мне нужен был учёт расходов по моделям в рублях и баланс провайдеров. Вместо того чтобы писать виджет руками, я попросил агента. Он сгенерировал расширение на TypeScript: фоновый опрос баланса, команда /balance, разбивка стоимости сессии по моделям. Логика — в одном файле, события session_start/session_shutdown, регистрация slash-команд через pi.registerCommand. Через пару итераций с LSP-диагностикой расширение заработало. Это не магия — это обычный код, просто написанный агентом по моему ТЗ.

guardrails вместо «спрашивать перед каждым действием»

Нельзя просто так дать доступ агенту ко всей инфраструктуре. Первая попытка — собственное расширение confirm-all.ts, которое спрашивало подтверждение перед каждым вызовом инструмента. Это быстро стало невыносимо: агенты работают в цикле из десятков вызовов, подтверждать каждый — значит свести на нет весь смысл автоматизации. К тому же расширение не работало в сессиях субагентов.

Решение — готовый пакет с умным фильтром: он анализирует содержимое каждого вызова (shell, пути, паттерны) и спрашивает подтверждение только на рискованное, а чтение и безопасные операции пропускает тихо. Как именно устроен мой набор ограничений — в следующем разделе; здесь важен сам ход: я не стал терпеть неподходящий инструмент, а попросил агента найти и поставить расширение, которое закрывает боль.

Принцип остаётся тем же, что и всегда в нашей профессии: сперва пишем Ansible-роли вместе с агентом, потом тестируем (--check, отдельное окружение), и только потом применяем. Просто сокращается время между написанием автоматизации и её применением. Агент — это junior с идеальной памятью, которому ты доверяешь периферию, но не доверяешь ключи от проды без подтверждения.

Экономика и контроль расходов

Без таблиц и сумм — суть в другом. Провайдеров моделей много: где-то получается дешевле, где-то дороже. Прямых ссылок не даю — выбирайте под свою юрисдикцию и бюджет. Главное, что pi не привязывает вас ни к одному из них.

Реальный рычаг экономии — не цена модели, а объём input-токенов. Каждый ход агент пересылает провайдеру весь накопленный контекст. Длинная сессия с десятками прочитанных файлов сжирает входные токены гораздо быстрее, чем дорогая output-генерация. Отсюда три приёма, которые реально экономят:

1. Субагенты с изолированным контекстом. «Разберись в кодовой базе» — это работа для субагента scout: он читает десятки файлов в своём окне и возвращает сжатую выжимку. Родительская сессия не тащит весь этот объём в свой контекст. Десять прочитанных файлов стоили бы дорого в основной сессии — у scout‘а они стоят копейки, а назад приходит только суть.

2. Маршрутизация моделей по ролям. Разведку (scout), веб-исследование (researcher), документацию (docs-writer) отправляем на дешёвые модели — им не нужен глубокий reasoning. Сложные правки (worker) и ревью (reviewer) — на модели помощнее. Это настраивается в settings.json одной записью на каждого агента.

3. Фоновая память на дешёвой модели. Длинные сессии компактируются — наблюдения и рефлексии готовятся фоновым воркером на самой дешёвой модели, а не на основной. Когда контекст переполняется, готовая память подставляется мгновенно, без долгой суммаризации за дорогие токены.

Конфиг в Git позволяет держать расходы под контролем: вы видите, какие модели и для каких агентов прописаны, и можете осознанно двигать ползунок «дёшево/медленно» ↔ «дороже/быстрее» под задачу.

Безопасность и границы

Тут стоит вернуться к тому, о чём я писал выше: сам по себе pi минималистичен, и всё, что касается ограничений и контроля, — это тоже расширения. Из коробки агент не знает, что rm -rf / — это плохо; этому его учат. Границы — не встроенная опция, а часть того самого «пластилина», который вы лепите под себя. Ниже — не догма, а просто мой опыт; у вас он сложится свой.

• Фильтр опасных команд. Расширение анализирует каждую bash-команду до выполнения и спрашивает подтверждение только на рискованное: rm -rf, sudo, chmod, обращения к .env и ключам. На чтение и безопасные операции — молчит. Спрашивать перед каждым вызовом инструмента невыносимо (агент работает в цикле из десятков вызовов), поэтому «умный фильтр» вместо «спрашивать всё» — это ровно тот случай, когда расширение закрывает реальную боль.

• Контроль путей. Доступ к файлам вне рабочего каталога — через явный вопрос. Агент не лезет в соседние проекты без разрешения.

• Секреты. Ansible-секреты — в ansible-vault, пароль от vault — отдельно от репозитория. Ключи провайдеров моделей — в файле, который исключён из Git.

Правило одно и неизменно: агент предлагает, человек подтверждает необратимое. Роли пишутся и тестируются в --check, применяются — после проверки. Это та же дисциплина, что и без агента; просто теперь границу держит инструмент, а не ваша сила воли в три часа ночи.

Чек-лист «попробовать за вечер»

Хотите проверить, не ваша ли это сказка? Вот путь с самого начала.

1. Установите pi с сайта pi.dev. Там короткая инструкция: одна команда — и агент установлен.

2. Подключите модель. pi работает с любым OpenAI-compatible провайдером — российский шлюз, self-hosted через vLLM/Ollama, что угодно под вашу юрисдикцию и бюджет. Ключ задаётся переменной окружения или кладётся в auth.json.

3. Заведите отдельный репозиторий под конфигурацию. Туда вы будете складывать то, как именно хотите взаимодействовать с ИИ: настройки, расширения, скиллы, инструкции. Положите ~/.pi/ в Git, auth.json и sessions/ — в .gitignore. С этого момента ваш сетап переносим между машинами.

4. Начните настраивать взаимодействие. В корне вашего инфра-репозитория создайте AGENTS.md — окружение, хосты, где секреты, что нельзя трогать. Напишите PLAN.md — что хотите автоматизировать, простым языком. Попросите агента написать первую Ansible-роль — что-нибудь простое: обновление пакетов, установка веб-сервера, hardening SSH. Прогоните ansible-playbook --check и посмотрите, как агент правит по диагностике.

Через неделю вы обнаружите, что конфигурация в Git обросла расширениями (большинство написаны самим агентом), AGENTS.md разросся, ролей стало несколько, а документация пишется сама.

Вместо вывода

Для сисадмина агент — не замена, а усилитель. Он берёт рутину — написание ролей, конфигов, документации, циклы правки по диагностике, — и оставляет вам то, ради чего вы и пошли в эту профессию: проектирование, расследование, решения. Инженер, который учится вместе с агентом и развивает инфраструктуру, — это не инженер, которого заменили. Это инженер, которому дали напарника, не спящего в ночную смену.

Если не хочется собирать с нуля — начните с готового: конфигурация pi, описанная в этой статье, лежит в моём GitLab — gitlab.com/bespam/pi. Берите, изучайте, переделывайте под себя — это и есть тот самый «пластилин».

Замыкайте агентов на инфраструктуру, замыкайте инфраструктуру на агентов, и не забывайте подтверждать rm -rf.