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

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

Переход к JSON-ответу с заданной схемой стал точкой отсчета: появился контракт с моделью, появилась возможность встраивать ее в бекенд.

Но важно понимать ограничение: модель хорошо работает только с текстом. Все остальное — это логика вокруг модели, и ее пишет разработчик

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

Это особенно критично в агентных сценариях, где промпт формируется динамически: важно, чтобы в него попадало именно то, что нужно, и именно в том виде, в котором нужно

Управлять нужно не только промптом, но и всем, что его окружает: историей выполнения, результатами RAG, состоянием задачи. Это и есть контекст-инжиниринг. Разница с обычным промтингом в том, что здесь разработчик контролирует весь информационный поток, который поступает в модель, а не только текст инструкции. Качество работы агента сильно зависит от того, насколько точно сформирован этот контекст.

Context window — это бюджет внимания модели. После заполнения 40% контекста отдача падает: recall модели деградирует, а рассуждения начинают ломаться

Инструмент (tool) — это не функция, как может показаться. Это структурированный JSON, описывающий функцию. Модель ничего не вызывает сама: она возвращает объект с именем функции и аргументами, а дальше код вызывает реальную функцию и передает результат обратно.

Все, что происходит вокруг модели, — MCP, скиллы, произвольные функции — строится поверх этого же механизма

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

Это вытекает из предыдущего пункта: если вы управляете контекстом, то и данные, которые в него попадают, вы храните сами, а не полагаетесь на то, что агент их восстановит

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

Агент без управляемого состояния — это черный ящик: непонятно, что он делает прямо сейчас и на каком этапе находится

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

Human Layer считает этот фактор принципиальным, хотя он и вызывает споры: у части разработчиков есть возражения против обязательного присутствия пользователя в цикле

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

Что именно даст лучший результат в конкретном случае — заранее неизвестно. Важна возможность менять порядок и состав компонентов и не переписывать всю систему

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

Именно так работают современные агентные окружения, в том числе Cursor: он получает ошибку и пытается ее исправить, а не останавливается

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

Подход тот же, что в микросервисах: маленький агент с четкой зоной ответственности проще отлаживать, заменять и тестировать. Для сложных задач несколько микро-агентов соединяются в детерминированный DAG.

Хорошо, если агент ограничен 3-20 шагами

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

Чем привычнее среда, тем выше вероятность, что агентом будут пользоваться

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

Один контекст — один запуск агента

Как 12-Factor App в свое время задала стандарты для облачной разработки, так и эти принципы могут стать ориентиром для тех, кто строит AI-native приложения. Они не привязаны к конкретному языку или фреймворку, а значит, могут работать на любом стеке.

А как вы строите своих агентов? Делитесь опытом в комментариях и заходите в канал, если еще не с нами.