Интенсив 21–22.11 · БесплатноБесплатный 2-дневный интенсив по вайбкодингу 21–22 ноября в 16:00 МСК (Сб–Вс) · Живой Поток 3 стартует 23.11Записаться бесплатно →Поток 3 (23.11)
РелизAPI / Продукт · В работуHabr AI→ оригинал

Разработчик запер кодинг-агента в YAML-клетку: 18 инструментов и 12 скиллов

Кодинг-агент хорошо пишет код, но автоматизации для бизнеса он на десятой правке тихо ломает: например, переписывает промпт, и никто не замечает. Автор AQVEN описал workflow в YAML поверх Pydantic AI, а агента пустил к графу только через MCP-сервер: 18 инструментов и 12 скиллов (готовых инструкций). Ошибки видны уже на сборке, как в типизаторе. Если агент пишет ваши ИИ-пайплайны, сначала постройте ему жёсткое окружение.

AI-обработка оригинала Habr AI; редакция Hamidun News
Разработчик запер кодинг-агента в YAML-клетку: 18 инструментов и 12 скиллов
Источник: Habr AI. Коллаж: Hamidun News.
Слушать статью
Паспорт материала и цифры
ПараметрДанные
ПервоисточникHabr AI ↗
Главный редактор
Aqven check гоняет flow на заглушкахбез ключей, сети и затрат на токены
Ключевой факт #2Тестовые примеры агенту не выдают, поэтому подогнать правку нельзя
Ключевой факт #3Studio показывает цену и время каждого узла и запускает flow с середины

Представьте, что вы поручили кодинг-агенту собрать ИИ-автоматизацию для службы поддержки. Первые правки проходят нормально. Но на десятой-пятнадцатой агент незаметно переписывает промпт или ломает соседний шаг, а вы узнаёте об этом от клиента. Автор инструмента AQVEN решил эту проблему так. Весь workflow описан в YAML и Markdown-файлах поверх фреймворка Pydantic AI (это Python-библиотека для работы с LLM). Агент получил доступ к графу только через MCP-сервер, то есть стандартный набор инструментов для ИИ-агентов. Таких инструментов 18, а ещё есть 12 скиллов, то есть готовых инструкций для типовых задач. Всё вместе образует жёсткое окружение, из которого агент не выходит. Это личный инженерный опыт, а не бенчмарк, и полезен он тем, кто выпускает LLM-пайплайны в продакшен.

Важная оговорка: автор сам делает AQVEN. Это wrapper над Pydantic AI с лицензией source-available. Цифр вроде «ошибок стало на N% меньше» в материале нет, так что ниже описан подход, а не доказанный эффект.

Почему готовые фреймворки не спасают

LangGraph, Pydantic AI, CrewAI, Mastra и VoltAgent умеют стримы, параллельные ветки, структурированный JSON-вывод и схемы входа. Observability, то есть трассировка вызовов, тоже есть: Langfuse, LangSmith, Arize Phoenix, Braintrust. По словам автора, этого мало, когда workflow пишет агент.

Сложный пайплайн собирается из паттернов: map-reduce, LLM-as-a-judge (одна модель оценивает ответы другой), repair-цикл (исправление неудачного ответа), расходящееся и сходящееся генерирование. Каждый паттерн умножает число вызовов. Через несколько итераций в трейсе тысячи записей, а у мультимодальных моделей вызовы ещё и принимают разные типы данных. Понять, что именно получила модель на входе, особенно если промпт собирается из кучи контекста, почти невозможно. Фреймворк даёт трейс, но не даёт человеку способа его прочитать.

Три слоя: YAML, harness и Studio

Слой 1: декларативный workflow. Весь flow лежит в Markdown и YAML-файлах, код подключается только там, где он нужен. Граф описан в файле Flow: вход, выход, контекст и порядок узлов. В примере автора это кейс поддержки бренда умного освещения из 17 узлов. Там есть разбор вложений, голосование за интент клиента, форма с repair, ответ из базы знаний и панель судей.

Каждый узел — папка из трёх файлов. В .node.yaml лежат связи, в .inference.yaml контракт входа и выхода с типами и лимитами (например, текст не длиннее 4000 символов, не более 20 сигналов). Промпт хранится в *.prompt.md как шаблон с ветвлениями и переиспользуемыми фрагментами. Поэтому ошибки видны на этапе сборки, как у статического типизатора. Команда aqven check валидирует каждый файл и симулирует прогон каждого flow с заглушками вместо моделей. Ключи и сеть не нужны, токены не тратятся, так что проверку можно гонять после каждой правки.

Слой 2: harness для агента. Это окружение, в котором агент живёт и из которого не выходит. В него входят MCP-сервер с 18 инструментами и 12 скиллов. Граф агент правит не прямой записью файлов, а через инструмент flow_patch с CAS: правка, сделанная на устаревшей версии, просто не применится. Хуки Claude Code после каждого изменения сами запускают aqven check, pyright и pytest. Инструмент prompt_preview показывает точный собранный промпт узла. Тестовые примеры для оценки результата агенту не выдаются, и подогнать правку под тесты нельзя. Команда aqven new создаёт проект сразу с AGENTS.md, CLAUDE.md и .mcp.json, так что агент готов к работе без настройки.

Слой 3: Studio. Агент может поменять тысячу строк за раз, и вручную это не отревьюить. Поэтому отладчик показывает не дерево спанов, а структуру flow: у каждого узла видны тип, статус, цена и время. Вложенные ветки раскрываются как матрицы вызовов, а в каждой ячейке есть модель, вход, промпт, выход и результат проверки.

Что это даёт на практике

С точки зрения затрат полезны две вещи. Во-первых, можно запустить не весь flow, а диапазон узлов, в том числе с середины на выходах прошлых прогонов. Один шаг перепроверяется без оплаты всего конвейера. Во-вторых, панели экспериментов позволяют сравнить модели по качеству, цене и поведению в разных ситуациях. Для мультимодальных входов это важно: модели там ведут себя по-разному и дают свои баги.

Ограничения понятны. Инструмент привязан к экосистеме Pydantic AI и Python, а настроен прежде всего под Claude Code. Лицензия source-available, а не классический open source. Публичных замеров надёжности нет. Но сама идея переносится на другие стеки. Если агент пишет ваши автоматизации, дайте ему узкий канал правок с версионированием, проверку без обращения к модели, скрытый от него набор тестов и читаемый для человека разбор прогона. Тогда незаметная порча промпта превращается в красный статус на сборке.

Код и документация лежат на GitHub (lastonoga/AQVEN) и на сайте aqvenstudio.com.

Сюжет

Вопросы и ответы по материалу

Что известно по теме: почему готовые фреймворки не спасают?

LangGraph, Pydantic AI, CrewAI, Mastra и VoltAgent умеют стримы, параллельные ветки, структурированный JSON-вывод и схемы входа. Observability, то есть трассировка вызовов, тоже есть: Langfuse, LangSmith, Arize Phoenix, Braintrust. По словам автора, этого мало, когда workflow пишет агент. Сложный пайплайн собирается из паттернов: map-reduce, LLM-as-a-judge (одна модель оценивает ответы другой), repair-цикл (исправление неудачного ответа), расходящееся и сходящееся генерирование.

Что известно по теме: три слоя: YAML, harness и Studio?

Слой 1: декларативный workflow. Весь flow лежит в Markdown и YAML-файлах, код подключается только там, где он нужен. Граф описан в файле Flow: вход, выход, контекст и порядок узлов. В примере автора это кейс поддержки бренда умного освещения из 17 узлов. Там есть разбор вложений, голосование за интент клиента, форма с repair, ответ из базы знаний и панель судей. Каждый узел — папка из трёх файлов.

Что известно по теме: что это даёт на практике?

С точки зрения затрат полезны две вещи. Во-первых, можно запустить не весь flow, а диапазон узлов, в том числе с середины на выходах прошлых прогонов. Один шаг перепроверяется без оплаты всего конвейера. Во-вторых, панели экспериментов позволяют сравнить модели по качеству, цене и поведению в разных ситуациях. Для мультимодальных входов это важно: модели там ведут себя по-разному и дают свои баги. Ограничения понятны. Инструмент привязан к экосистеме Pydantic AI и Python, а настроен прежде всего под Claude Code.

ЖХ
Жемал Хамидун — CPO Alpina Digital, продакт-менеджер AlpinaGPT. Делает AI-продукты с 2019 года. Hamidun News — pet project, который вырос в production-агрегатор с 6000+ читателей.
✦ Практика · Hamidun Academy

Соберите рабочего ИИ-агента или сервис своими руками без ручного кода

В Академии Жемала Хамидуна (academy.hamidun.com) открыт бесплатный 72-часовой тест-драйв: интерактивные скетч-уроки по Claude Code и Cursor, живой Tech Radar и готовые шаблоны агентов.

Открыть 72ч бесплатный доступ →Интенсив по Вайб-кодингу
Что вы думаете?
Загружаем комментарии…