Как я собрал 33 ИИ-агента на одном движке: пять примеров с кодом

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

Когда я начинал, каждый агент писался с нуля под конкретную задачу. Через несколько проектов стало ясно: 90% кода повторяется — обработка входа, вызов модели, постобработка. Так родилась идея общего движка. Сейчас все агенты используют один и тот же каркас, а различия только в конфигурации. Это позволило сократить время разработки нового агента с недель до дней и упростить поддержку.

Пять агентов с разных полюсов границы

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

Второй агент — помощник по учёбе. Модель генерирует объяснения и примеры, но проверка фактов и расчётов остаётся за кодом. Это гарантирует точность ответов, даже если модель ошибается в деталях. Код выступает как фильтр, который не пропускает фактическую ошибку.

Третий агент — ассистент для жены. Здесь граница проходит почти вплотную к модели: код только маршрутизирует запросы и сохраняет историю. Это позволяет максимально гибко реагировать на запросы, но требует доверия к модели. В данном случае это оправдано, так как задачи не критичны к ошибкам.

Четвёртый агент — тьютор образовательной программы. Модель ведёт диалог, но код жёстко контролирует сценарий и собирает метрики. Это обеспечивает структурированность обучения и возможность анализировать эффективность. Код задаёт рамки, а модель наполняет их содержанием.

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

Предыстория и контекст

Идея собрать всех агентов на одном движке возникла из практической необходимости. Каждый агент — это, по сути, один и тот же каркас: входной запрос, контекст, вызов модели, постобработка. Первые версии агентов были написаны с нуля под каждую задачу, что приводило к дублированию кода и сложностям в поддержке. Когда накопилось пять-шесть агентов, стало очевидно: нужен общий движок. Так появился единый Docker-образ и кодовая база, на которой сейчас крутятся все 33 агента.

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

Как это работает?

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

Технические подробности

Движок построен на Python, использует FastAPI для API и LangChain для оркестрации. Каждый агент — это набор шагов, определённых в YAML-конфиге. Шаги могут быть трёх типов: код, вызов модели, внешний сервис. Конфиг описывает, какие шаги выполняются последовательно, какие параллельно, и какие данные передаются между ними. Это позволяет менять поведение агента без изменения кода — достаточно отредактировать конфиг.

Замеры показали, что при таком подходе среднее время ответа агента составляет около 1,5 секунды, из которых до 80% занимает вызов модели. Код выполняется за миллисекунды. Стоимость одного запроса варьируется от 0,01 до 0,1 доллара в зависимости от используемой модели и длины контекста. В металлургическом холдинге агент обрабатывает до 10 тысяч запросов в день, и это не создаёт нагрузки на серверы.

Кого затронет и как

Разработчики, которые строят ИИ-агентов, найдут здесь практическую методологию: как разделить ответственность между кодом и моделью, как избежать типичных ошибок, как масштабировать агентов без переписывания кода. Для бизнеса это означает снижение затрат на разработку и поддержку: один движок вместо множества разрозненных решений. Для пользователей — более стабильные и предсказуемые ассистенты, которые реже ошибаются и быстрее отвечают.

В российских компаниях, особенно в промышленности и образовании, такие агенты уже внедряются. Автор отмечает, что в металлургическом холдинге агент помог сократить время подготовки отчётов с нескольких часов до минут. В образовательной программе тьютор повысил вовлечённость студентов на 30%.

Что будет дальше

Автор планирует расширить движок: добавить поддержку мультимодальных моделей, улучшить инструменты мониторинга и отладки, а также опубликовать открытую версию. В ближайшие месяцы ожидается выход статьи с подробным описанием архитектуры и примерами конфигов.

Итог

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