Агенты: модель в цикле с инструментами и целью

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

Что такое агент

Агент — это модель, помещённая в цикл с целью и набором инструментов. Упрощённо каждый шаг выглядит так:

1. План / рассуждение — модель смотрит на цель и текущее состояние и решает, что сделать следующим.
2. Действие — вызывает инструмент: читает файл, запускает тест, ищет по коду, правит строку.
3. Наблюдение — получает результат действия в контекст.
4. Повторяет цикл, учитывая результат, — и так, пока цель не достигнута или пока не упрётся в лимит, который вы задали заранее: число шагов или потраченные деньги (про лимиты — ниже, без них цикл не останавливается).

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

Откуда агент знает, что закончил

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

Критерий бывает трёх видов, и они сильно разного качества.

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

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

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

Как превратить задачу без теста в задачу с критерием — три приёма, которые работают почти всегда:

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

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

Чем агент отличается от запроса

Разница — в автономности. Обычный запрос выполняет ровно то, что вы сказали, за один ход. Агент сам разбивает задачу на шаги, сам выбирает инструменты, сам реагирует на промежуточные результаты и сам решает, когда закончить.

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

Планирование и агенты внутри агентов

Цикл из четырёх шагов — упрощение, и на первом же инструменте вы увидите две вещи, которых в нём нет.

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

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

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

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

Где агенты сильны, а где ломаются

Сильны, когда задача:

• разбивается на шаги с проверяемым результатом (тест прошёл / не прошёл, код скомпилировался);
• требует реакции на промежуточные итоги (не угадаешь заранее весь путь);
• терпит несколько попыток и имеет понятный критерий готовности.

Ломаются, когда:

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

Контроль обязателен

Автономность требует границ — иначе галлюцинация на одном шаге тихо утечёт в результат:

• Ограничивайте инструменты и права — агент должен уметь ровно необходимое; необратимое — через подтверждение человека.
• Ставьте лимиты — на число шагов и на стоимость: цикл легко нагенерирует сотни дорогих вызовов.
• Делайте результат проверяемым — давайте агенту проверяемый критерий (тесты, компиляция), по которому он и вы понимаете, что цель достигнута; затем проверяйте итог как любой результат ИИ.
• Держите человека в контуре на важных решениях — агент предлагает, человек утверждает то, что дорого откатить.

Сколько стоит одна сессия

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

Считать надо не шаги, а токены, и главное свойство такое: на каждом шаге агент переотправляет всю историю. Пусть системные правила и описания инструментов — 5 тысяч токенов, и каждый шаг добавляет в историю в среднем 2 тысячи (ваша реплика, вызов, результат чтения файла). Тогда вход первого шага — 5 тысяч, десятого — около 25, тридцатого — около 65. Сложив, получаем: тридцать шагов — это примерно миллион входных токенов, а не тридцать раз по пять тысяч. Отсюда и ощущение «почему так дорого»: стоимость сессии растёт примерно как квадрат числа шагов.

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

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

Агент застрял: что делать

Сюжет, знакомый всем после первой недели: агент третий раз правит одно и то же место, тест всё падает, ответы становятся всё более уверенными и всё менее осмысленными. Это состояние узнаётся по трём признакам: повторение (те же файлы, те же правки), рост объяснений без роста результата и смена подхода на каждой попытке («попробую иначе» три раза подряд).

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

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

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

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

Спросить, что мешает. «Остановись и опиши, что именно не получается и какой информации тебе не хватает» — часто получаете точный ответ («не понимаю, откуда берётся это значение»), который решается одной подсказкой.

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

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

Когда агент не нужен

Раздел про поломки перечисляет условия, а решение из них не выведено. Оно простое: в этих случаях агента не берут.

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

Необратимый шаг внутри задачи. Удалить данные, отправить письмо клиентам, выкатить в прод, изменить схему базы на живой системе. Не потому, что агент глупее вас, а потому, что цена ошибки не покрывается экономией времени. Такие шаги человек делает сам, а агент готовит к ним всё остальное.

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

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

Разведка в незнакомом коде, когда вам нужно понять самому. Агент прекрасно объяснит и сделает, но понимание останется у него. Если этот код вам предстоит поддерживать, полчаса своего чтения окупятся.

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

Что это значит на практике

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

Глубже: git как страховка сессиирасширенное

«Откатитесь на последний хороший шаг» из статьи про работу с агентами не исполняется без механизма, и механизм это git. Агент, который правит десять файлов за минуту, без страховки превращает откат в ручную археологию.

Правила простые. Сессия начинается с новой ветки: всё, что сделает агент, остаётся в ней, и main не пострадает при любом исходе. Каждый проверенный шаг это коммит: тест прошёл, вы посмотрели диф, зафиксировали; агенту можно поручить и сам коммит после вашей проверки, но не автоматически после каждого своего действия, иначе история состоит из шума. Между коммитами git diff показывает ровно то, что агент изменил с последней проверенной точки, и это главный инструмент ревью его работы: не читать файлы, а читать разницу.

Откат становится штатной операцией: git checkout -- . или git restore . отменяет всё после последнего коммита, git reset --hard возвращает к нужному шагу, git stash откладывает попытку, чтобы попробовать другой подход, не теряя первый. Когда агент ушёл не туда, дешевле откатить и переформулировать задачу, чем просить его «исправить», накапливая ошибки в контексте. Параллельные попытки живут в отдельных рабочих деревьях (git worktree): два агента над одной задачей в двух каталогах, и побеждает та ветка, где результат лучше.

Чего агенту не дают: push --force, переписывания истории общей ветки, слияния в main без вашего ревью и коммитов с файлами, которые он не должен был трогать (.env, ключи). Это правила в настройках агента, а не устная договорённость. И последняя привычка: в конце сессии ветка либо слита через обычный pull request, либо удалена; ветки-сироты от сессий недельной давности это тот же мусор, что и незакрытые вкладки.

Глубже: что уходит провайдеру вместе с контекстомрасширенное

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

Ответ: на серверы провайдера модели, целиком. Промпт, файлы, которые агент открыл, вывод команд, содержимое базы, которое он запросил инструментом, всё это входит в контекст и отправляется с каждым вызовом. Что провайдер с этим делает, определяет договор: у потребительских тарифов данные могут использоваться для обучения и храниться долго; у корпоративного доступа и доступа через API обычно обещают не обучать на данных и хранить ограниченное время (иногда с режимом без хранения вовсе), с указанием региона обработки и документом об обработке данных, который подписывают. Без такого договора считайте, что всё отправленное стало общедоступным.

Отсюда правила, что нельзя класть в контекст: секреты и ключи (их не должно быть в репозитории и в переменных, к которым агент имеет доступ), персональные данные пользователей (выгрузки базы, логи с email, обращения), данные под соглашением о неразглашении, код, который по договору с заказчиком не может покидать контур. Персональные данные при необходимости обезличивают до отправки: имена и адреса заменяют метками и возвращают после ответа.

Когда нужна своя модель. Если данные по закону или договору не могут покидать контур (закрытые сегменты, данные граждан под требованиями локализации, о чём статьи про 152-ФЗ), модель ставят у себя: открытые модели работают на собственных видеокартах, качество ниже старших моделей провайдеров, зато данные не уходят. Промежуточный вариант это корпоративный шлюз к провайдеру: один канал с журналом, маскированием и лимитами, через который ходят все агенты компании, вместо ключей у каждого разработчика.

Коротко

• Агент это модель в цикле: план, действие, наблюдение, повтор до цели или лимита; сильна на задачах с проверяемым результатом, ломается без критерия готовности.
• Автономность требует границ: минимальные инструменты, лимиты шагов и денег, проверяемый критерий, человек на важных решениях.
• Git страхует сессию: ветка на сессию, коммит на проверенный шаг, diff как ревью, откат как штатная операция, никаких push --force и слияний без ревью.
• Всё, что агент прочитал, уходит провайдеру; без договора об обработке считайте это публичным; секреты, персональные и закрытые данные не кладут в контекст, а при требованиях локализации ставят свою модель или шлюз.
• Критерий «готово» бывает машинным (тест, сборка), наблюдаемым (список условий) и «покажи мне» — последний означает отсутствие критерия; задачу без теста превращают в задачу с тестом, попросив сначала проверку.
• Настоящий агент планирует до действий (план стоит прочитать на крупной задаче) и запускает подчинённых агентов, чтобы шум поиска не оставался в основном контексте.
• Стоимость растёт как квадрат числа шагов, потому что вся история переотправляется: тридцать шагов — около миллиона входных токенов, поэтому короткие сессии дешевле длинных.
• Застрявшего агента не подбадривают: предел в три попытки, потом новая сессия с итогом, сужение до диагноза без правок, недостающие данные или своя рука.
• Агента не берут на задачу в пять строк, на необратимый шаг, на задачу без способа проверки и на ту, которую вы сами не понимаете.

Что пощупать

Цикл агента целиком — полсотни строк, и их можно прочитать: remodov/marketplace-system, практикум курса, четыре языка на выбор. Ни ключа, ни интернета, ни зависимостей: модель в тестах подменена сценарием — проверяется не её сообразительность, а поведение цикла вокруг неё.

Код: Java — agent; Python — examples/llm/python; Go — examples/llm/go; Node — examples/llm/node.

Сделаем сами

Ветка side-b4-agent-tools — цикл вынут, тесты красные, условие по ссылке в TASK.md.

Что почитать дальше

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