Создание автономного агента-программиста на CPU без GPU: практическое руководство по созданию self-learning системы на базе Qwen и LangGraph

Архитектурная Концепция и Функциональные Модули Системы

Создание полностью автономной системы-агента для разработки программного обеспечения представляет собой сложную инженерную задачу, требующую тщательно продуманной архитектуры, способной объединить несколько дисциплин: машинного обучения, инженерии ПО и теории управления. Цель состоит не просто в генерации кода по текстовому запросу, а в создании замкнутого цикла самообучения и самосовершенствования, где агент самостоятельно выполняет весь жизненный цикл разработки от начала до конца, включая написание документации. Для начинающих разработчиков такой инструмент может служить мощным помощником, имитирующим опыт senior-разработчика и обучаясь на собственном опыте. Архитектура такого агента должна быть модульной, что позволяет независимо развивать и оптимизировать каждый компонент. Анализ предоставленных материалов и передовых практик в области AI-агентов позволяет выделить четыре ключевых функциональных модуля, составляющих ядро системы: модуль оркестратора, модуль генератора кода, модуль исполнителя и модуль документирования. Эти модули в совокупности обеспечивают реализацию заявленного цикла «запрос → код → исправление → тестирование → документация».

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

Модуль генератора кода отвечает за преобразование абстрактного текстового запроса в конкретный, исполняемый код. Его производительность напрямую зависит от качества используемой большой языковой модели (LLM). Современные LLM, такие как серии Qwen, CodeLlama и DeepSeek, демонстрируют значительные достижения в этой области, но их эффективность сильно зависит от правильного применения техник инструктирования. Для повышения качества первой же попытки генерации модуль должен не только получать исходный промпт, но и контекст из долговременной памяти. Это особенно важно для задачи предотвращения повторных ошибок. Перед каждой генерацией кода модуль должен загружать историю известных ошибок и их решений, формируя расширенный промпт, который просит модель избегать ранее допущенных паттернов. Например, если агент многократно ошибался в работе с определенным API или допускал типичные ошибки синтаксиса, эта информация должна быть представлена модели в качестве предупреждения. Кроме того, модуль должен уметь не только генерировать новый код, но и исправлять существующий на основе сообщений об ошибках. Для этого используется другой, более специализированный промпт, который предоставляет модели оригинальный код, текст ошибки и просьбу исправить только ту часть кода, которая привела к сбою.

Модуль выполнителя играет роль «песочницы» для запуска сгенерированного кода. Безопасность является здесь главным приоритетом. Прямой запуск произвольного кода, сгенерированного LLM, без защиты представляет серьезную угрозу для системы, так как модель может случайно или из-за «галлюцинаций» сгенерировать команды вроде rm -rf /. Поэтому рекомендуется использовать изолированные окружения, такие как Docker-контейнеры или утилиты типа nsjail, которые ограничивают права доступа и ресурсы, доступные запускаемому процессу. Задача модуля — запустить код, перехватить его стандартный вывод (stdout) и поток ошибок (stderr), а также получить код возврата. На основе этих данных оркестратор принимает решение о дальнейших действиях. Если код завершается успешно (код возврата равен 0), выполнитель сообщает об этом. Если возникает ошибка времени выполнения, компиляции или превышается установленное время выполнения (тайм-аут), модуль собирает текст ошибки и передает его обратно оркестратору для анализа и последующего исправления. Также этот модуль может быть ответственен за запуск автоматизированных тестов, если они были сгенерированы или написаны заранее.

Наконец, модуль документирования является заключительным этапом в жизненном цикле агента. После того как код успешно выполняется и проходит все предусмотренные тесты, модуль документирования активируется для создания понятной и структурированной инструкции по использованию созданной программы. Этот модуль использует тот же LLM, что и модуль генератора кода, но с другим набором инструкций. Ему предоставляется описание задачи, исходный промпт, а также финальный, исправленный код. Задача модели — проанализировать код и сгенерировать документацию, объясняющую, что делает программа, какие параметры она принимает, как ее запустить и какие результаты можно ожидать. Формат документации может быть Markdown, HTML или любой другой, удобный для пользователя. Этот шаг завершает цикл разработки и превращает сгенерированный код в полноценный, готовый к использованию продукт.

В дополнение к этим четырем основным модулям, в архитектуру необходимо интегрировать модуль долговременной памяти. Хотя он не является самостоятельным блоком в цикле выполнения, его роль в обеспечении самообучения агента абсолютно критична. Этот модуль отвечает за хранение и поиск информации об ошибках и успешных решениях, накопленных в ходе работы. Как будет подробно рассмотрено далее, это может быть реализовано через простые файлы (JSON, Markdown) или более сложные векторные базы данных. Каждая новая ошибка, ее решение и контекст её возникновения сохраняются в этой базе знаний. При следующих итерациях генерации кода эта информация используется для формирования контекста, тем самым позволяя агенту учиться на своих прошлых ошибках и становиться все более эффективным. Таким образом, архитектура автономного агента представляет собой сложную, но логически выстроенную систему, где каждый модуль выполняет свою уникальную функцию, а их взаимодействие, организованное модулем оркестратора, обеспечивает достижение конечной цели — создания качественного программного продукта с минимальным человеческим вмешательством.

Выбор и Настройка Инфраструктуры под Жёсткие Ресурсные Ограничения

Реализация автономного агента-программиста на аппаратном обеспечении с ограниченными ресурсами, таким как CPU (например, AMD Ryzen 5 поколения Zen 3) и 20 ГБ оперативной памяти без дискретной видеокарты, требует особого внимания к выбору программного стека. Основная сложность заключается в том, чтобы найти баланс между производительностью LLM, необходимой для качественной генерации и исправления кода, и потреблением системных ресурсов. Любая ошибка в этой части может привести к неконкурентоспособной скорости работы или даже к невозможности запуска системы из-за нехватки памяти. Анализ современных open-source решений показывает, что существует зрелый и хорошо поддерживающийся стек технологий, который идеально подходит для таких условий. Этот стек включает в себя среду выполнения для LLM, фреймворк для оркестрации агентов и инструменты для управления зависимостями.

Центральным элементом локальной инфраструктуры является среда выполнения, отвечающая за запуск и обслуживание большой языковой модели. Для данной задачи лучшим выбором является Ollama. Этот инструмент был специально разработан для упрощения развертывания и использования LLM на локальном оборудовании, будь то CPU или GPU. Главное преимущество Ollama заключается в его простоте установки и использования: достаточно одной команды для установки на большинство Linux-дистрибутивов, включая Ubuntu, и еще одной команды для загрузки и запуска модели. Ollama имеет минимальные системные требования: для старта достаточно 8 ГБ оперативной памяти, что делает его идеальным кандидатом для системы с 20 ГБ RAM. Что еще более важно, Ollama отлично работает на CPU, предлагая широкий выбор квантованных версий популярных моделей в формате GGUF. Квантование — это процесс снижения точности числовых весов модели (например, с 16-битных чисел с плавающей запятой до 4-битных целых чисел), что значительно уменьшает размер модели на диске и в оперативной памяти, часто с незначительной потерей в качестве. Для системы с 20 ГБ RAM использование квантованных моделей является не просто рекомендацией, а необходимостью. Например, 7-миллиардная модель Qwen2.5-Coder-7B в квантованном виде (например, Q4_K_M) занимает около 4-6 ГБ оперативной памяти, что оставляет значительный запас для операционной системы, самого Ollama и других процессов. Производительность на CPU будет ниже, чем на GPU, но для интерактивной работы вполне приемлемой. Ожидаемая скорость генерации составляет от 5 до 15 токенов в секунду на современном многоядерном процессоре, таком как Ryzen 5. Это позволяет пользователю видеть результат работы агента в разумные сроки.

Вторым ключевым компонентом стека является фреймворк для оркестрации агентов. Как уже упоминалось, для реализации сложной логики автономного цикла, управления состоянием и возможностей человеческого вмешательства наиболее подходящим решением является LangGraph. LangGraph — это Python-библиотека, разработанная командой LangChain, которая позволяет строить stateful (состоятельные) и stateless (бесконечные) агентские рабочие процессы в виде графов. Это идеально соответствует задаче создания цикла «генерация → исправление → тестирование». В LangGraph каждый шаг в этом цикле представляется как узел в графе, а переходы между шагами — как ребра. Возможность создавать циклические графы позволяет реализовать бесконечный цикл исправлений, который продолжается до тех пор, пока код не будет исправлен. LangGraph предоставляет мощные механизмы для управления состоянием, что позволяет легко передавать данные (текст ошибки, исправленный код, история выполнения) между узлами графа. Кроме того, LangGraph имеет встроенную поддержку Human-in-the-loop (HITL) парадигмы, что является обязательным требованием для данного проекта. С помощью функции interrupt или контрольных точек (checkpoint) можно приостановить выполнение графа, сохранить его текущее состояние в базу данных или файл, и дождаться ввода от пользователя. Это позволяет реализовать сложную логику взаимодействия с человеком, когда агент предлагает несколько вариантов действий и ждет от пользователя осознанного выбора, а не простого подтверждения.

Для сборки и управления всеми необходимыми библиотеками Python, помимо LangGraph и клиента OpenAI (который используется для взаимодействия с Ollama через API), могут потребоваться и другие зависимости. В частности, для реализации долговременной памяти потребуется векторная база данных (например, ChromaDB) и модель для создания эмбеддингов (например, sentence-transformers). Все эти инструменты являются open-source и имеют легкую конфигурацию, что соответствует духу проекта. Установка производится стандартными средствами Python, такими как pip.

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

1. Установка операционной системы: Рекомендуется использовать современный дистрибутив Linux, такой как Ubuntu 22.04 LTS или 24.04 LTS, поскольку большинство руководств и скриптов ориентированы именно на него.
2. Установка Ollama: Скачивание и установка осуществляется через официальный скрипт: curl -fsSL https://ollama.com/install.sh | sh. После установки необходимо убедиться, что сервис запущен и доступен.
3. Загрузка и проверка LLM: Выполнение команды ollama pull <model_name> для скачивания выбранной модели. Например, ollama pull qwen:qwen2.5-coder:7b-instruct-q4_K_M. После загрузки можно протестировать модель с помощью команды ollama run <model_name>, отправив ей простой запрос, чтобы убедиться в ее корректной работе.
4. Настройка Python-окружения: Создание виртуального окружения для проекта (например, с помощью venv или conda) для изоляции зависимостей. Установка необходимых библиотек: pip install langgraph openai chromadb sentence-transformers python-dotenv.
5. Настройка сети: Ollama по умолчанию запускает API сервер на http://localhost:11434. Необходимо убедиться, что нет конфликтов с другими службами и что приложение может обращаться к этому адресу. В коде приложения для взаимодействия с LLM будет использоваться клиент OpenAI с указанием base_url="http://localhost:11434/v1".

Этот стек (Linux + Ollama + LangGraph + Python) представляет собой надежную, масштабируемую и полностью контролируемую платформу для разработки и эксплуатации автономного агента-программиста. Он не требует подписки на облачные API, гарантирует конфиденциальность данных, так как вся обработка происходит локально, и полностью соответствует заданным аппаратным и программным ограничениям. Хотя начальная настройка может показаться сложной для начинающего разработчика, существует множество подробных руководств и примеров, которые значительно упрощают этот процесс.

Сравнительный Анализ Бесплатных LLM для Кодогенерации и Самоисправления

Выбор основной движущей силы системы — большой языковой модели (БЯМ) — является наиболее критическим решением при создании автономного агента-программиста. Именно от качества и характеристик LLM зависят способность системы генерировать корректный код, находить и исправлять ошибки, а также эффективно работать в условиях ограниченных ресурсов. Задача требует особого внимания к двум аспектам: точности исправления кода и способности модели работать с контекстом накопленных ошибок. Для систем с 20 ГБ оперативной памяти и только CPU-вычислениями (процессор Ryzen 5 Zen 3) выбор должен быть сделан на моделях, которые предлагают наилучший баланс между производительностью и потреблением ресурсов. На основе анализа предоставленных источников, три основных кандидата заслуживают детального рассмотрения: Qwen2.5-Coder, CodeLlama и DeepSeek-Coder.

Qwen2.5-Coder выделяется как один из самых сильных игроков в нише кодогенерации. Серия моделей Qwen, разработанная Alibaba, демонстрирует высокие результаты на множестве стандартных бенчмарков для оценки кодовых моделей, таких как HumanEval и MBPP. Например, Qwen2.5-Coder-7B-Instruct достигает внушительного показателя PASS@1 в 83.5% на HumanEval, что значительно превосходит GPT-3.5-Turbo (52.2%) и приближается к результатам закрытых моделей. Особо примечателен его потенциал в задачах исправления кода. В техническом отчете указано, что Qwen2.5-Coder-7B-Instruct демонстрирует отличные способности к исправлению кода, достигая PASS@1 точности в 51.9% на соответствующих задачах, что значительно выше многих конкурентов. Это качество делает его идеальным кандидатом для роли основного генератора кода и исправителя ошибок в нашей системе. Кроме того, существуют специализированные версии моделей, такие как Qwen3-Coder, которые позиционируются как лидеры в своей категории, а Qwen2.5-Coder-7B-Instruct считается одним из лучших бесплатных кодовых ассистентов, способных работать локально на системах с 32 ГБ RAM. Однако у Qwen есть и потенциальные недостатки. Некоторые пользователи отмечают, что модель может склонна к «галлюцинациям» и иногда испытывает трудности с задачами, которые обрабатываются более стабильными моделями, такими как DeepSeek. Тем не менее, общая производительность и наличие специализированных версий делают Qwen2.5-Coder наиболее перспективным выбором.

CodeLlama, серия моделей от Meta, является классическим и широко известным решением в мире open-source кодогенерации. Она часто рекомендуется как хороший стартовый вариант для локального развертывания, особенно в связке с Ollama. Однако, согласно некоторым сравнительным данным, CodeLlama уступает современным моделям Qwen в чистой производительности. Например, в одном из сравнений Qwen2.5-Coder-32B достигает 92.7% на HumanEval, в то время как CodeLlama 7B Instruct набирает всего 34.8%. Это огромный разрыв, который говорит о том, что для задач, требующих высокой точности и сложного логического мышления, CodeLlama может оказаться менее эффективным. Тем не менее, CodeLlama остается достойным кандидатом, особенно для менее сложных задач или если пользователь предпочитает экосистему Meta. Как и Qwen, CodeLlama доступен в различных версиях и размерах, что позволяет выбрать оптимальный вариант для конкретных ресурсов.

DeepSeek-Coder является еще одним сильным конкурентом, который регулярно упоминается в обсуждениях и сравнениях. Этот модельный ряд демонстрирует производительность, сопоставимую с лидерами рынка, и часто превосходит как CodeLlama, так и ранние версии Llama 3 в задачах кодогенерации. Одним из преимуществ DeepSeek, на которое указывают некоторые пользователи, является его меньшая склонность к «галлюцинациям» по сравнению с Qwen, хотя он и может уступать ему в некоторых специфических задачах. Это делает DeepSeek-Coder хорошей альтернативой, если модель Qwen будет давать слишком много ошибок в реальных сценариях. DeepSeek также доступен в разных размерах, включая 1.5-миллиардную и 32-миллиардную модели, что позволяет гибко управлять ресурсами .

Характеристика	Qwen2.5-Coder-7B-Instruct	CodeLlama-7B-Instruct	DeepSeek-Coder-V2
Производительность (HumanEval PASS@1)	83.5%	34.8%	81.1% (Lite версия)
Производительность (MBPP)	Значительно выше GPT-3.5-Turbo	Данные не доступны	Данные не доступны
Способность к исправлению кода	Высокая (PASS@1: 51.9%)	Данные не доступны	Упоминается как сильная сторона, но без конкретных цифр
Требования к VRAM/RAM	~6-8 GB для 7B версии (квантованной)	~8-10 GB для 7B версии (квантованной)	~8-10 GB для 7B версии (квантованной)
Ключевые преимущества	Высочайшая точность кодогенерации и исправления, наличие специализированных версий	Широко распространенная и понятная экосистема Meta	Стабильность, меньшая склонность к «галлюцинациям»
Ключевые недостатки	Может «галлюцинировать», что снижает надежность в некоторых случаях	Ниже производительность по сравнению с Qwen и DeepSeek	Может уступать Qwen в абсолютной производительности

Исходя из этого анализа, для создания системы, ориентированной на максимальную точность исправления кода и эффективную работу с контекстом ошибок, Qwen2.5-Coder-7B-Instruct является наиболее предпочтительным выбором. Его высокие баллы на бенчмарках, подтвержденные несколькими источниками, и специализированная оптимизация для кодовых задач делают его идеальным кандидатом. Квантованная версия этой модели (например, Q4_K_M) впишется в системные ограничения в 20 ГБ оперативной памяти, оставляя достаточный запас для операционной системы и других процессов. Скорость работы на CPU Ryzen 5 Zen 3 будет приемлемой для интерактивного использования, хотя и не сверхбыстрой. Важно отметить, что производительность LLM сильно зависит от качества инструкций, поэтому даже при выборе лучшей модели, ее эффективность будет во многом определяться тем, как агент формулирует запросы и представляет ей контекст. Для данной системы потребуется разработать два специализированных шаблона инструкций: один для первоначальной генерации кода с учетом истории ошибок, и другой для целенаправленного исправления кода по сообщению об ошибке. Такой подход позволит максимально раскрыть потенциал выбранной модели и добиться высокой степени автономии и качества результата.

Реализация Долговременной Памяти: От Простых Файлов до Векторных Баз Данных

Ключевым элементом, отличающим настоящего автономного агента от простого генератора кода, является его способность к самообучению. Заявленная цель — «соберет ошибки в файл, что-бы потом их не повторять больше» — является воплощением этого принципа. Реализация долговременной памяти позволяет системе накапливать знания о типичных ошибках, сложных случаях и эффективных решениях, что превращает ее в постоянно развивающийся инструмент. Подходы к реализации памяти эволюционируют от очень простых и легковесных методов к более сложным, но и более мощным системам семантического поиска. Для системы, работающей на ограниченных ресурсах (20 ГБ RAM), выбор правильного уровня сложности памяти является стратегическим решением, влияющим на производительность, масштабируемость и эффективность обучения.

Наиболее простой и интуитивно понятный способ реализации памяти — это использование обычных файлов, таких как JSON или Markdown. В прототипе, представленном в диалоге, используется JSON-файл (error_memory.json), в который записываются объекты с полями «ошибка» и «решение». Преимущества этого подхода очевидны: он чрезвычайно прост в реализации, не требует никаких внешних зависимостей, и вся база знаний является читаемой и редактируемой человеком в любом текстовом редакторе. Это обеспечивает полную прозрачность и контроль над содержимым памяти. Однако у такого подхода есть два фундаментальных недостатка. Во-первых, это линейный поиск: при каждой новой итерации агент должен прочитать весь файл и проверить новую ошибку на совпадение с каждой из ранее сохраненных. По мере роста базы знаний скорость поиска будет линейно уменьшаться, что сделает систему медленной. Во-вторых, поиск основан на точном текстовом совпадении. Если агент впервые встречает ошибку, которая семантически аналогична старой, но сформулирована по-другому (например, «AttributeError: ‘list’ object has no attribute ‘append’» vs «Object of type ‘list’ doesn’t have ‘append’ method»), он не сможет найти релевантное решение.

Для преодоления этих ограничений современные AI-агенты используют более продвинутые системы долговременной памяти на основе векторных баз данных. Этот подход позволяет реализовать семантический поиск, где система находит релевантные записи на основе их смысла, а не дословного совпадения текста. Процесс работы такой системы выглядит следующим образом: каждая запись в памяти (например, описание ошибки и ее исправление) преобразуется в числовой вектор фиксированной длины, называемый вложением, с помощью специальной нейронной сети (эмбеддинг-модели). Эти векторы затем сохраняются в специализированной базе данных, оптимизированной для быстрого поиска по векторам. Когда возникает новая ошибка, ее текст также преобразуется в вектор, и система выполняет поиск в базе данных наиболее близких (по евклидовой или косинусной метрике) векторов. Таким образом, она может найти старые ошибки, описанные совершенно другими словами, но имеющие схожую причину.

Для выбора векторной базы данных для локальной системы с ограниченными ресурсами необходимо учитывать несколько факторов: простота установки, требования к памяти и производительность. На основе анализа предоставленных материалов, можно выделить три основных кандидата:

1. ChromaDB: Этот инструмент является идеальным стартовым вариантом для разработки локальных AI-приложений. Его главное преимущество — невероятная простота. Установка сводится к одной команде pip install chromadb, а API максимально интуитивно понятен и нативен для Python. ChromaDB поддерживает режим «in-process», при котором база данных работает в том же процессе, что и приложение, что полностью устраняет сетевую задержку и упрощает развертывание. Для системы с 20 ГБ RAM это отличный выбор для начала, так как он не требует сложной настройки и имеет относительно низкие требования к ресурсам. Хотя ChromaDB может уступать более производительным решениям в масштабе, его простота делает его незаменимым инструментом для прототипирования и быстрой разработки.
2. LanceDB: Это более современное и элегантное решение, которое позиционируется как «SQLite для векторных данных». LanceDB является файловой базой данных, что означает, что вся база знаний хранится в одном или нескольких файлов на диске. Это кардинально упрощает развертывание и портability, так как нет необходимости запускать и поддерживать отдельный сервер. Более того, написанная на Rust, LanceDB демонстрирует отличную производительность и эффективность использования памяти, что делает ее крайне привлекательной для ресурсоограниченных систем. В одном из бенчмарков LanceDB показала наивысшую скорость записи (ингестии) среди сравниваемых баз данных. Для нашего случая, где важна не только скорость, но и экономия памяти, возможности LanceDB, такие как нулевая копия версионирования и оптимизированный формат хранения, могут стать решающими.
3. Qdrant: Если говорить о самом производительном и функциональном решении, то это Qdrant. Также написанный на Rust, он предлагает высокую производительность, продвинутые возможности для фильтрации по метаданным и, что самое важное для нас, различные методы квантования векторов. Квантование позволяет сжимать векторы, значительно уменьшая их объем в памяти (до 32 раз), что критически важно для системы с 20 ГБ RAM. Qdrant также поддерживает распределенные режимы работы, но для нашей задачи достаточно будет его локальной одиночной версии. Хотя его установка и настройка немного сложнее, чем у ChromaDB, его производительность и возможности по управлению памятью делают его лучшим выбором для продвинутой системы, которая должна обрабатывать большое количество данных в долгосрочной перспективе.

Векторная База Данных	Ключевые Преимущества	Ключевые Недостатки	Рекомендация по использованию
ChromaDB	Очень простая установка и использование; нативный Python API; встроенный режим работы без сервера.	Производительность может снижаться при больших объемах данных (>500K векторов); нет встроенного квантования.	Идеальный стартовый вариант для прототипирования и разработки.
LanceDB	Файловая архитектура (как SQLite); высокая производительность и эффективность по памяти; не требует отдельного сервера.	Меньше распространён и имеет меньше сторонних интеграций по сравнению с ChromaDB.	Отличная альтернатива ChromaDB, если нужна максимальная простота и эффективность.
Qdrant	Высочайшая производительность; поддержка квантования для экономии памяти ; мощные возможности фильтрации.	Более сложная установка и настройка по сравнению с ChromaDB/LanceDB.	Оптимальный выбор для продвинутой системы, где важна производительность и управление ресурсами.

Для реализации памяти в нашем агенте рекомендуется следовать итеративному подходу. Начать следует с ChromaDB из-за его простоты. Будет достаточно написать две функции: одна для добавления новой ошибки и ее решения в ChromaDB, и вторая для поиска наиболее релевантных старых ошибок на основе векторного представления новой ошибки. Эмбеддинги для кода и ошибок можно генерировать с помощью хорошо зарекомендовавшей себя и легковесной модели all-MiniLM-L6-v2 из библиотеки sentence-transformers. Эта модель была обучена на огромном количестве данных, включая код, и хорошо подходит для задач семантического поиска. Если в процессе развития системы окажется, что поиск в ChromaDB становится слишком медленным или неэффективным, можно будет безболезненно перейти на LanceDB, а при необходимости — на Qdrant для максимальной производительности и контроля над памятью.

Оркестрация Агентских Циклов с Человеко-Центричным Управлением

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

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

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

1. generate_code_node: Вызывает LLM для генерации или исправления кода. На вход ему подаются промпт и контекст из долговременной памяти (векторной базы данных).
2. execute_code_node: Запускает сгенерированный код в песочнице и возвращает результат (вывод, ошибку, код возврата).
3. analyze_output_node: Анализирует результат выполнения. Если код выполнился успешно, поток направляется к узлу запуска тестов. Если произошла ошибка, эта ошибка сохраняется в долговременную память, и поток возвращается к узлу генерации кода для исправления.
4. run_tests_node: Запускает набор автоматизированных тестов. Если тесты провалены, информация о провале передается обратно в generate_code_node. Если все тесты пройдены, поток идет к узлу документирования.
5. write_documentation_node: Генерирует финальную инструкцию.
6. human_in_the_loop_node: Это специальный узел, который встраивается в критические точки цикла.

Ключевая особенность LangGraph, реализующая человеческое вмешательство, — это механизм контрольных точек и прерывания. Когда агент достигает точки, где требуется человеческое решение (например, после N неудачных попыток исправить код, или при обнаружении потенциально опасной для системы операции), он может вызвать функцию прерывания. Это прерывание останавливает выполнение графа и сохраняет его текущее состояние. Приложение, управляющее агентом, перестает быть «черным ящиком» и получает доступ ко всему текущему контексту: истории выполнения, сгенерированному коду, накопленным ошибкам. Теперь можно реализовать интерфейс для пользователя, который будет видеть эту информацию и предлагать ему выбор из нескольких стратегий.

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

• Стратегия 1: «Перегенерировать код с расширенным контекстом». Агент может предложить изменить свой внутренний промпт, добавив больше информации о задаче или ожидаемом результате. Это может помочь LLM лучше понять намерение и сгенерировать более корректное решение.
• Стратегия 2: «Предоставить пример правильного решения». Агент может попросить пользователя написать небольшой фрагмент кода, который демонстрирует правильный подход к решению проблемы. Этот пример можно использовать как дополнительный пример в промпте для последующих попыток генерации, что является мощной техникой инструктирования.
• Стратегия 3: «Провести глубокий анализ и предложить альтернативный алгоритм». Здесь агент может использовать свои способности к рассуждению, чтобы проанализировать проблему и предложить принципиально другой подход к решению задачи. Например, если код медленно работает, агент может предложить использовать другой алгоритм со сложностью $O(n \log n)$ вместо $O(n^2)$.
• Стратегия 4: «Завершить выполнение с ошибкой». Если ни один из предыдущих вариантов не помог, или если проблема кажется слишком сложной для текущей конфигурации, агент может предложить прекратить попытки и предоставить пользователю финальный, самый исправленный вариант кода и подробное описание проблем.

Представление этих стратегий с их четким описанием плюсов и минусов позволяет пользователю (даже начинающему разработчику) принимать осознанные решения, а не просто нажимать кнопку «да/нет». Это превращает агента из пассивного исполнителя в активного помощника. После того как пользователь делает свой выбор, приложение снова запускает граф LangGraph, но уже с обновленным состоянием, которое включает в себя выбор пользователя. Выполнение возобновляется с того места, где было сделано прерывание, и агент продолжает свою работу, используя новую информацию.

Такой подход к управлению, известный как «человек в цикле» (HITL), является стандартом де-факто для создания надежных и доверенных AI-систем. LangGraph предоставляет все необходимые инструменты для его реализации, включая управление состоянием, контрольные точки и возможность возобновления выполнения. Это позволяет создать систему, которая сочетает в себе автономность и эффективность, характерные для AI, с интуицией и экспертным знанием человека. Для начинающего разработчика это означает, что он всегда находится «под колесом» и может направлять процесс, когда сталкивается с проблемой, которую не может решить сам, а агент — самостоятельно.

Пошаговая Методика Развертывания и Эксплуатации Системы

Для практической реализации предложенной архитектуры автономного агента-программиста на оборудовании с процессором Ryzen 5 Zen 3 и 20 ГБ оперативной памяти, необходимо выполнить ряд последовательных шагов. Данная методика разработана для начинающих разработчиков и предполагает поэтапную настройку окружения, интеграцию компонентов и запуск первого автономного цикла. Она основана на использовании современных open-source инструментов, обеспечивающих полную локальную работу и максимальную гибкость.

Шаг 1: Подготовка операционной системы и установка основных зависимостей

Первым шагом является подготовка базовой операционной среды. Рекомендуется использовать современный дистрибутив Linux, такой как Ubuntu 22.04 LTS или 24.04 LTS, так как большинство инструкций и скриптов для локальных LLM ориентированы именно на него.

1. Обновление системы: После установки Ubuntu выполните обновление списка пакетов и самих пакетов: sudo apt update && sudo apt upgrade -y.
2. Установка Python и pip: Убедитесь, что у вас установлен Python версии 3.10 или выше, а также менеджер пакетов pip. Обычно они поставляются вместе с Ubuntu. Проверить версию можно командой python3 --version.
3. Установка Ollama: Ollama является центральным элементом для локального запуска LLM. Следуйте официальной инструкции для быстрой установки: curl -fsSL https://ollama.com/install.sh | sh. После установки запустите службу и добавьте ее в автозагрузку: sudo systemctl enable ollama и sudo systemctl start ollama.

Шаг 2: Загрузка и проверка Large Language Model (LLM)

Выбор модели — Qwen2.5-Coder-7B-Instruct — является ключевым решением, обеспечивающим высокое качество кодогенерации и исправлений при относительно невысоких требованиях к ресурсам.

1. Загрузка модели: Выполните в терминале команду для загрузки квантованной версии модели, оптимизированной для экономии памяти: ollama pull qwen:qwen2.5-coder:7b-instruct-q4_K_M. Квантование (в данном случае, 4-битное) позволяет модели поместиться в оперативную память системы с 20 ГБ, оставляя свободные ресурсы для операционной системы и других процессов.
2. Проверка работы модели: Чтобы убедиться, что модель загружена и работает корректно, выполните команду ollama run qwen:qwen2.5-coder:7b-instruct-q4_K_M и введите простой запрос, например, «Напиши на Python функцию для вычисления факториала числа». Если модель вернет корректный код, значит, ее можно использовать в дальнейшей разработке.

Шаг 3: Настройка Python-окружения и установка библиотек

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

1. Создание виртуального окружения: python3 -m venv agent_env
2. Активация окружения: source agent_env/bin/activate
3. Установка необходимых библиотек: В активированном окружении выполните команду pip install langgraph openai chromadb sentence-transformers python-dotenv.
   • langgraph: Фреймворк для оркестрации агентского цикла.
   • openai: Клиент для взаимодействия с API Ollama (который совместим с API OpenAI).
   • chromadb: Векторная база данных для долговременной памяти.
   • sentence-transformers: Библиотека для работы с моделями эмбеддингов, такими как all-MiniLM-L6-v2.
   • python-dotenv: Удобный способ управления переменными окружения, например, для хранения имени модели.

Шаг 4: Создание структуры проекта и реализация кода агента

Создайте структуру проекта и реализуйте основной скрипт на Python, который будет содержать всю логику агента.

1. Создание файлов: Создайте в корневом каталоге проекта следующие файлы:
   • main.py: Основной скрипт, где будет реализован StateGraph LangGraph.
   • .env: Файл для хранения переменных окружения (например, имя модели).
   • task.txt: Файл с текстовым описанием задачи для агента.
   • generated_code.py: Файл, в который будет записываться сгенерированный код.
   • tests.py: Файл для хранения тестов (может быть пустым на старте).
   • INSTRUCTIONS.md: Файл для финальной документации.
2. Реализация StateGraph: В main.py создайте Python-скрипт, который определяет граф состояний. Он должен включать узлы для генерации кода, его выполнения в песочнице, анализа ошибок, запуска тестов и написания документации. В критических точках, где требуется человеческое вмешательство, реализуйте логику прерывания и ожидания ввода.
3. Реализация долговременной памяти: Добавьте в код функции для работы с ChromaDB. Функция add_to_memory(error, fix) должна преобразовывать текст ошибки и ее решения в эмбеддинг с помощью all-MiniLM-L6-v2 и сохранять его в ChromaDB. Функция search_memory(query) должна делать то же самое с новой ошибкой и возвращать наиболее релевантные старые записи, которые будут добавлены в контекст промпта для LLM.

Шаг 5: Настройка песочницы для выполнения кода

Безопасность — критический аспект при выполнении кода, сгенерированного AI. Простое использование subprocess.run() небезопасно.

1. Использование Docker: Наиболее надежным способом является запуск сгенерированного кода в изолированном Docker-контейнере. В узле execute_code_node вашего графа LangGraph команда для запуска должна вызывать docker run с ограниченными правами и объемом памяти.
2. Настройка Docker: Установите Docker на вашу систему (sudo apt install docker.io). Добавьте своего пользователя в группу docker, чтобы не использовать sudo при каждом запуске: sudo usermod -aG docker $USER. Перезагрузите систему или войдите заново.
3. Скрипт-обертка: Создайте простой Python-скрипт-обертку, который будет принимать на вход путь к файлу с кодом, запускать его в Docker-контейнере (например, на базе образа python:3.10-slim), перехватывать stdout, stderr и код возврата, а затем возвращать результат в основной скрипт агента.

Шаг 6: Запуск и тестирование агента

Готовый к работе агент можно запустить.

1. Подготовка задачи: Напишите краткое, но четкое описание задачи в файле task.txt. Например: «Напиши программу на Python, которая читает CSV файл с данными о продажах (колонки: дата, товар, количество, цена), рассчитывает общую выручку для каждого товара и выводит результат в формате JSON».
2. Запуск агента: Выполните в терминале: python main.py.
3. Наблюдение за процессом: Агент начнет свой цикл. Вы сможете наблюдать за его действиями в консоли: как он генерирует код, сохраняет его, запускает в песочнице, анализирует ошибки, исправляет код и так далее. Если в процессе возникнет ситуация, требующая человеческого вмешательства, агент остановится и предоставит вам интерфейс для выбора одной из стратегий.
4. Анализ результата: Если агент успешно завершит работу, проверьте сгенерированный файл generated_code.py и INSTRUCTIONS.md. Запустите код вручную, чтобы убедиться в его корректности.

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