Почти все мы только учимся работать с агентами. Даже опытные команды иногда управляют агентами так, что те приносят больше вреда, чем пользы. HumanLayer сформулировал 12 принципов того, как делать и настраивать агентов правильно. Каждый пункт отвечает на вопрос, что работает хорошо, а что стабильно приводит к проблемам.
1. Структурированный вывод
До появления структурированного вывода от языковой модели нельзя было ожидать детерминированного результата: она возвращала произвольный текст. Подключить ее к реальной системе было крайне сложно.
Переход к JSON-ответу с заданной схемой стал точкой отсчета: появился контракт с моделью, появилась возможность встраивать ее в бекенд.
Но важно понимать ограничение: модель хорошо работает только с текстом. Все остальное — это логика вокруг модели, и ее пишет разработчик
2. Контроль промпта
Промпт должен быть написан разработчиком, а не сгенерирован автоматически. Когда вы отдаете формирование промпта фреймворку, вы теряете контроль над тем, что именно видит модель. В итоге агент ведет себя не так, как вы ожидаете, а понять причину сложно: вы не знаете, что именно ушло в модель.
Это особенно критично в агентных сценариях, где промпт формируется динамически: важно, чтобы в него попадало именно то, что нужно, и именно в том виде, в котором нужно
3. Контекст-инжиниринг
Управлять нужно не только промптом, но и всем, что его окружает: историей выполнения, результатами RAG, состоянием задачи. Это и есть контекст-инжиниринг. Разница с обычным промтингом в том, что здесь разработчик контролирует весь информационный поток, который поступает в модель, а не только текст инструкции. Качество работы агента сильно зависит от того, насколько точно сформирован этот контекст.
Context window — это бюджет внимания модели. После заполнения 40% контекста отдача падает: recall модели деградирует, а рассуждения начинают ломаться
4. Инструменты как структурированный вывод
Инструмент (tool) — это не функция, как может показаться. Это структурированный JSON, описывающий функцию. Модель ничего не вызывает сама: она возвращает объект с именем функции и аргументами, а дальше код вызывает реальную функцию и передает результат обратно.
Все, что происходит вокруг модели, — MCP, скиллы, произвольные функции — строится поверх этого же механизма
5. Хранение состояния
Если агент в цикле несколько раз обращается к одним и тем же данным и каждый раз заново их запрашивает, это расточительно и медленно. Данные стоит сохранять и переиспользовать внутри сессии.
Это вытекает из предыдущего пункта: если вы управляете контекстом, то и данные, которые в него попадают, вы храните сами, а не полагаетесь на то, что агент их восстановит
6. Статус агента
Хороший агент умеет менять свое состояние и предоставлять к нему доступ. Он может поставить задачу на паузу, возобновить выполнение и среагировать на триггер в нужный момент.
Агент без управляемого состояния — это черный ящик: непонятно, что он делает прямо сейчас и на каком этапе находится
7. Участие человека в процессе
Когда пользователь принимает решения в процессе выполнения задачи, результат получается лучше. Это не означает, что агент должен постоянно спрашивать разрешения. Но там, где человек может сделать выбор и дать дополнительный контекст, это стоит предусмотреть.
Human Layer считает этот фактор принципиальным, хотя он и вызывает споры: у части разработчиков есть возражения против обязательного присутствия пользователя в цикле
8. Компонуемость
После вызова языковой модели начинается этап обработки результата. Этот этап можно строить из разных компонентов в разных комбинациях: суммаризаторы, ретриверы, ре-ранкеры, джаджи, оркестраторы. Жесткой формулы нет.
Что именно даст лучший результат в конкретном случае — заранее неизвестно. Важна возможность менять порядок и состав компонентов и не переписывать всю систему
9. Работа с ошибками
Старые агенты умирали при первой же ошибке. Сейчас подход другой: ошибку нужно зафиксировать, добавить ее описание в контекст и заново запустить задачу. На основе информации об ошибке модель, скорее всего, предложит другое решение.
Именно так работают современные агентные окружения, в том числе Cursor: он получает ошибку и пытается ее исправить, а не останавливается
10. Маленькие агенты
Агент должен решать одну конкретную задачу. Монолитный агент берется за все сразу, но плохо масштабируется и поддерживается, как, например, монолитный сервис в бэкенде.
Подход тот же, что в микросервисах: маленький агент с четкой зоной ответственности проще отлаживать, заменять и тестировать. Для сложных задач несколько микро-агентов соединяются в детерминированный DAG.
Хорошо, если агент ограничен 3-20 шагами
11. Работа в среде пользователя
Агент взаимодействует с пользователем там, где пользователь работает. Если он работает в Slack — агент должен быть доступен через Slack. Не стоит создавать отдельное окружение только для взаимодействия с агентом.
Чем привычнее среда, тем выше вероятность, что агентом будут пользоваться
12. Stateless-агенты
Агент не должен управлять своим контекстом самостоятельно. Он запускается, получает контекст, выполняет задачу, сохраняет нужные артефакты и завершает работу. Следующий запуск — новый агент с новым контекстом. Агент, который сам суммаризирует свою историю и самостоятельно управляет окном контекста, выведен из-под вашего контроля.
Один контекст — один запуск агента
Как 12-Factor App в свое время задала стандарты для облачной разработки, так и эти принципы могут стать ориентиром для тех, кто строит AI-native приложения. Они не привязаны к конкретному языку или фреймворку, а значит, могут работать на любом стеке.
А как вы строите своих агентов? Делитесь опытом в комментариях и заходите в канал, если еще не с нами.
Автор: ai_fucked_up
