Kitabı oxu: «AI-агенты за 3 недели 67 шаблонов, команд и чек-листов для надёжного исполнителя.»

Что внутри

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

Я написал её для тех, кто уже пробовал LLM-чат и столкнулся с тремя привычными бедами: модель говорит «готово», а по факту ничего не готово; агент забывает, что делал пять минут назад; а чуть отвлечёшься — и он уже выполнил rm -rf в неправильной директории. Все эти беды лечатся не «возьму модель помощнее», а системой — тем, что в книге называется harness, обвязкой.

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

Кому это читать

Начинающим разработчикам, которые уже пробовали LLM, но хотят собрать первого автономного агента — а не очередного чат-бота с кнопками.

Инженерам, уставшим от «преждевременного успеха»: модель говорит, что задача выполнена, а проверка показывает обратное. Эта книга объясняет, почему так происходит и как заставить агента реально проверять результат.

Техлидам и тимлидам, которые присматриваются к агентам для рутинных задач команды — ревью pull-реквестов, настройки CI/CD, работы с логами — и хотят понять, где тут реальная польза, а где хайп.

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

Не нужно быть ML-инженером. Базового умения читать код и работать в терминале достаточно: всё остальное вы получите по дороге.

Маршрут читателя

Книга построена по принципу «халва по граммам»: одна идея — одна порция. Главы идут по зависимостям, а не по темам, поэтому я рекомендую читать их по порядку. Каждая глава опирается на то, что объяснено в предыдущих, и заранее вводит крючок к следующей.

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

В конце книги — практический блок: чек-листы, шаблоны AGENTS.md, feature_list.json, progress.md, системного промпта и сводка команд Hermes. Если вы предпочитаете «сначала сделать, потом понять» — можно начать с практического блока, собрать агента по шаблонам, а потом вернуться к главам за пониманием, почему шаблоны именно такие.

Моё обещание вам

Если вы хотя бы раз просили ChatGPT или Claude «настроить CI/CD для проекта» — вы знаете, как это обычно заканчивается. Модель уверенно рассказывает, что нужно сделать. Показывает куски конфигурации. Объясняет, какой шаг за каким идёт. Вы киваете, закрываете вкладку и идёте делать всё руками — потому что модель не может ни создать файл, ни запустить тесты, ни проверить, что получилось.

Это не баг модели.

Это её нормальное состояние. LLM по своей природе — это собеседник, а не исполнитель. Она генерирует текст в ответ на текст. И сколько бы вы её ни просили «действовать», она не откроет файл, не запустит команду и не отправит pull-реквест, потому что у неё нет для этого рук. Чтобы LLM стала агентом, ей нужна обвязка: инструменты, память, правила, верификация. Без обвязки вы получаете умного собеседника. С обвязкой — исполнителя.

Эта книга о том, как собрать такую обвязку. Не о моделях — их сделают за вас большие лаборатории, и каждую неделю выходит что-то новое. А о системе вокруг модели, которая превращает «говорящую голову» в рабочего ассистента: того, кто понимает задачу, выбирает инструмент, помнит контекст, проверяет результат и не сжёг ваш сервер к концу первого дня.

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

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

Глава 1. Почему ваш «умный чат-бот» бросает задачу на полпути

Представьте знакомую ситуацию. Вы ставите задачу: «настрой CI/CD для этого проекта». Чат-бот — неважно, какой именно — отвечает развёрнуто. Рассказывает про GitHub Actions, показывает yaml-конфигурацию, объясняет, какие шаги нужны: линтер, тесты, сборка Docker-образа, деплой на staging. Вы читаете, киваете, закрываете вкладку — и идёте делать всё это сами. Потому что бот ничего из перечисленного не сделал. Он только рассказал.

Это не дефект конкретной модели. Это её природа. Большая языковая модель по определению — это система, которая продолжает текст. Она предсказывает следующий токен на основе предыдущих. Когда вы спрашиваете «как настроить CI/CD», она отвечает текстом — потому что для неё это просто продолжение диалога. У неё нет ни терминала, чтобы запустить команду, ни файловой системы, чтобы записать конфиг, ни рук, чтобы нажать кнопку. Она не «не хочет» — она не может.

Поэтому, когда вы жалуетесь, что «агент снова бросил задачу», стоит уточнить: вы общались с агентом или с чат-ботом? Эти слова часто путают, а разница между ними — вся суть этой книги.

ОПРЕДЕЛЕНИЕ

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

Разница не семантическая, а архитектурная. Чтобы LLM стала агентом, вокруг неё собирают обвязку — набор компонентов, которые превращают «говорящую голову» в исполнителя. Эта обвязка и есть то, что я в этой книге называю harness. Без harness — чат-бот. С harness — агент.

Теперь вернёмся к нашему CI/CD. Если ту же задачу — «настрой CI/CD для этого проекта» — дать настоящему агенту, произойдёт другое. Агент прочитает структуру проекта. Поймёт, что это Python-репозиторий с pytest. Создаст файл .github/workflows/ci.yml. Прогонит тесты локально, чтобы убедиться, что они проходят. Запушит ветку. Проверит, что pipeline в GitHub Actions зелёный. И только тогда сообщит: «готово, пайплайн работает, вот ссылка». Разница не в качестве ответа — разница в том, что ответ вообще есть.

ПРИМЕР

Представьте, что вы попросили ассистента «настрой CI/CD». Он уверенно отвечает: «Сделано! Пайплайн настроен». Вы открываете репозиторий — файла нет. Спрашиваете снова — он показывает кусок yaml и говорит: «Вот, добавьте это в репозиторий». Вы добавляете. Запускаете. Падает. Спрашиваете — он извиняется и предлагает другой кусок. И так три часа.

Это и есть чат-бот, замаскированный под агента. У него нет инструмента для записи файла. У него нет инструмента для запуска тестов. У него нет верификации — он не может проверить, что его совет сработал. Поэтому он рапортует об успехе, которого не было. Это не «глупая модель» — это модель без рук.

ВАЖНО

Главный симптом, что вы общаетесь с чат-ботом, а не с агентом: модель говорит «готово», но вы не можете проверить это, не открыв ещё одну вкладку и не сделав что-то руками. Если каждое «сделано» требует от вас ручной проверки и доделки — у вашей модели нет рук. Ей нужен harness.

Откуда тогда берётся уверенность модели, что «всё готово»? Это интересный момент. LLM обучена продолжать текст так, как будто она компетентный собеседник. Когда её спрашивают «настроил?», она, не имея реального опыта, отвечает в стиле «да, конечно» — потому что в её обучающей выборке именно так отвечают ассистенты в подобных диалогах. Это не ложь в человеческом смысле. Это текстовая реконструкция поведения, которое модель никогда не выполняла. Поэтому верить модели на слово о завершении задачи — самый дорогой источник проблем в работе с агентами.

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

ЧТО СДЕЛАТЬ НА ПРАКТИКЕ

Вспомните последнюю задачу, которую вы пытались поручить LLM и которая провалилась. Запишите её. Рядом запишите, что именно пошло не так: модель соврала о завершении? Не смогла записать файл? Забыла контекст? Выполнила опасное действие? Эта запись пригодится в следующих главах — вы будете сверять её с компонентами и увидите, какого именно не хватило.

ИТОГ ГЛАВЫ

• Чат-бот отвечает на вопросы, агент — выполняет задачи. Разница в наличии рук, памяти и правил, а не в качестве модели.

• LLM по природе — это текстовый движок. У неё нет инструментов, чтобы действовать в мире. Без обвязки она остаётся собеседником.

• «Готово» из уст модели без верификации — это не отчёт, а текстовая реконструкция успеха. Верьте только проверяемому результату.

• Превращение чат-бота в агента — это инженерная задача, а не молитва «дай нам модель помощнее».

→ Чтобы агент мог «сделать», а не «рассказать», ему нужны пять компонентов. Каких именно — в следующей главе. Спойлер: один из них — модель, но далеко не первый по важности.

Глава 2. Пять частей, без которых агента не существует

В предыдущей главе мы выяснили: чтобы LLM стала агентом, ей нужна обвязка. Теперь посмотрим, из чего эта обвязка состоит. У любого агента — от простейшего CLI-бота до корпоративного ассистента в Telegram — есть пять компонентов. Если убрать любой из них, агент перестаёт быть агентом и превращается во что-то другое: в чат-бот, в скрипт, в галлюцинирующую модель или в закрытую систему без связи с внешним миром.

Я перечислю все пять, а потом разберём каждый по «грамму» — что это, зачем нужно и что случится, если его не станет.

ПЯТЬ КОМПОНЕНТОВ АГЕНТА

1. Языковая модель (LLM) — мозг, обрабатывающий запросы и генерирующий ответы. 2. Память — способность сохранять контекст между обращениями и сессиями. 3. Инструменты — действия во внешнем мире: чтение и запись файлов, терминал, веб-поиск. 4. Harness (обвязка) — явные правила и ограничения, которые задают границы поведения. 5. Каналы связи — интерфейсы, через которые вы общаетесь с агентом: CLI, мессенджер, веб-консоль.

1. Языковая модель — мозг

Это то, что у всех на слуху: GPT-4o, Claude, Qwen, DeepSeek, локальная Llama через Ollama. Модель принимает текст на вход и генерирует текст на выход. Без неё агент не существует — нечего «обвязывать». Но она не делает работу сама; она принимает решения внутри системы, которую вы построили.

Минимальное требование к модели для агента — контекстное окно не менее 64 000 токенов. Меньше — и агент не сможет вести многошаговый диалог с инструментами: каждый вызов инструмента добавляет в контекст его результат, и при коротком окне агент быстро забывает, с чего начал. Современные облачные модели дают 128K–200K, чего хватает для большинства задач.

Выбор модели зависит от трёх вещей: бюджета, требований к приватности и доступности в вашем регионе. Для первого проекта проще всего начать с облачной модели — OpenAI, Anthropic, DeepSeek, Alibaba Cloud Qwen — а потом, если понадобится полная приватность, перейти на локальную через Ollama или vLLM.

2. Память — почему агент не начинает с нуля

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

Память бывает нескольких уровней: краткосрочная (в рамках одной сессии — это контекстное окно модели), среднесрочная (прогресс задач, сохраняемый в файл progress.md), долгосрочная (база знаний и история прошлых взаимодействий). В шестой главе мы разберём её подробно — там есть свои тонкости. Пока достаточно запомнить: память — это отдельный компонент, который нужно проектировать, а не «он сам появится».