Как строить агентные графы

За время работы с графами за последние 4 месяца, я набил несколько крупных шишек в дизайне графов. В этом посте хочу поделиться главными выводами, чтобы вы не повторяли моих ошибок.

Сначала, моё определение графов:

Агентные графы (a.k.a workflow) — это ориентированные графы, допускающие циклы и описывающие передачу работы между агентами (узлами), работающими в цикле, по предопределённым переходам (рёбрам). Графы состоят из ветвлений, циклов, скриптов, и переходов (и их промптов и параметров).

Параллелизм - не панацея

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

Стандартная параллельная группа проверок может включать код-ревью, архитектурное ревью и scope review. Проблема начинается, когда эти этапы находятся внутри цикла.

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

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

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

Теоретически проблему можно решить умным роутером. Kent поддерживает это через script nodes: роутер может определить, завершил ли агент реализацию целиком или только адресовал фидбэк конкретного ревьюера (kent.sh - это мой бесплатный, открытый проект для построения агентных графов. Я упоминаю его потому что сам им пользуюсь и не знаю других подобных продуктов. Вы можете применить эти советы для любого подобного оркестратора).

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

На практике проблема решается проще: зависимые проверки нужно выполнять последовательно. В моих workflow архитектурное ревью всегда идет перед код-ревью. Только после одобрения архитектуры задача переходит на проверку кода.

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

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

Агенты должны иметь возможность оспорить фидбек

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

Но ревьюеры тоже не всегда дают правильный результат.

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

Например, scope review может забраковать тесты, которые буквально одним шагом ранее потребовало добавить код-ревью, посчитав без них верификацию задачи неполноценной.

При этом нельзя полностью доверять агенту самостоятельное разрешение подобных конфликтов. Даже с новыми моделями GPT-5.6 можно получить бесконечный цикл исправления надуманных или несуществующих проблем.

Я решаю это делегированием финального решения себе. Вы также можете передать его агенту-ПМу или организовать коммуникацию между несколькими агентами. Например, можно дать им ID сессий, чтобы они обсудили ситуацию и пришли к компромиссу.

Anthropic в своем недавнем исследовании говорят что проблема в модели. Я несогласен - это обязанность харнесса, и мои результаты выше доказывают это.

В графе обязательно должен быть механизм эскалации конфликтующего или сомнительного фидбэка - иначе ревью превращается в диктатуру, способную зациклить весь workflow.

Не забывайте о статических проверках

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

Изначально мой агент-реализатор самостоятельно запускал линтер, архитектурные и юнит-тесты, открывал PR и проверял поступающие комментарии. Затем я решил вынести эти действия в отдельные узлы агентного графа.

Теперь отдельный этап:

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

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

Не поручайте LLM работу, которую надежнее и дешевле может выполнить обычный скрипт. В масштабе workflow это дает существенную экономию.

Выбирайте модели под конкретные этапы

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

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

Kent решает эти проблемы, поэтому не бойтесь создавать разные роли для агентов. Например, ручной QA можно запускать на дешевых моделях вроде DeepSeek или Luna, которые почти ничего не стоят/не влияют на квоту подписки. Самым умным моделям при этом можно делегировать только критически важные этапы - например, планирование.

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

Начиная с версии 2.6 Kent нативно поддерживает выбор одним агентом модели, роли системного промпта и уровня мышления для следующего агента после перехода по ребру графа. Это позволяет:

• делегировать простые задачи и багфиксы моделям вроде Luna;
• запускать QA на дешевых моделях с большими лимитами;
• передавать простые решения локальным моделям;
• оставлять сложное планирование и критические проверки наиболее сильным моделям.

Следите за кэшами и временем между вызовами

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

спекулятивный компакт (для обычных сессий) выгоден с 88% контекста согласно слоп-графику. Для воркфлоу порог приходится на ~71%

Представьте, что агент-реализатор потратил 40 минут на исправление замечаний код-ревью. За это время кэши агентов-ревьюеров могли инвалидироваться. Когда они будут проверять работу во второй раз, Kent заранее выполнит компакт сессии, чтобы ревью продолжилось со свежим контекстом и без лишних расходов из-за промаха по кэшу.

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

В этом случае есть два основных варианта:

• использовать режим compact and continue в Kent - он похож на speculative compact, но компакт выполняется всегда;
• создавать более гранулярные чекпоинты, которые будут чаще возвращать работу агенту и сохранять кэши горячими.

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

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

Делайте узлы идемпотентными

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

Это нормально. Ненормально, когда граф не дает агенту никакого способа справиться с такой ситуацией. Каждая ошибочная строчка плана потенциально может привести к тысячам строк неправильного кода.

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

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

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

Kent поддерживает это нативно. Для узлов, связанных с реализацией, можно включить переиспользование контекста или опциональное начало новой сессии.

Также стоит адаптировать промпты: прямо укажите, что повторное получение задачи не означает необходимость начинать сначала. Kent уже добавляет соответствующие инструкции в prompting агентов во время workflow, но пользовательские промпты все равно могут неявно подразумевать работу с нуля.

Идемпотентные узлы, управляемые возвраты и корректное переиспользование контекста делают агентный граф устойчивым не только к ошибкам моделей, но и к реальной нелинейности разработки.