Telegram-канал tsingular - Технозаметки Малышева: Unsorted

Технозаметки Малышева

05 October 2025 17:02

12 Factor Agents - принципы разработки агентов

По следам от 12 Factor Apps, Декстер Хорти собрал ключевые принципы по разработке агентов, делюсь!

1) Преобразование естественного языка в вызовы инструментов. Агент интерпретирует команды в формализованные вызовы функций, а исполняет их — детерминированный код
2) Владей своими промптами (как кодом). Промпт — это артефакт. Его надо хранить, версионировать, тестировать и относиться к нему не как к важной части кода.
3) Управляй контекстом агента. Активно контролируй, что попадает в это окно. Убирай уже не нужное, суммаризируй, оставляй важное, выделяй ограниченные слоты под фичи — внимание модели ограниченно.
4) Вызов тулинга — это просто JSON. LLM генерирует название тула и параметры, остальное должен делать ваш детерминированный вход. Модель решает "что делать", а ваше приложение "как делать"
5) Держи тех.состояние и бизнес состояние вместе. Каждый шаг агента — это и логика, и данные. Всё в одном состоянии, чтобы потом не ковыряться по логам в поисках, где оно сломалось
6) API для управление циклом агента. Агент должен иметь простой API для запуска, приостановки и возобновления работы, уметь вставать на паузу и возвращаться к работе спустя время на каждом этапе жизненного цикла
7) Запрос к человеку — как инструмент. Любое обращение в процессе работы к человеку должно быть представлено агенту, как инструмент requestClarification(message:string)
8) Явно контролируйте логику исполнения. Модель лишь "говорит" что, а твой код решает стоит ли выполнять, когда и как.
9) Добавляйте ошибки исполнения инструментов в контекст. Если что-то упало, сократи информацию и добавь это в контекст агента. Пусть модель сама догадается, что дальше: повторить, спросить или изменить стратегию
10) Используйте малых специализированных агентов. Лучше много маленьких агентов, решающих узконаправленные задачи, чем один перегруженный агент всего
11) Доставляй агентов в любые интерфейсы, удобные пользователю. Slack, Telegram, веб, CLI — неважно. Главное — единый API и омниканальность. Пользователь не должен думать, где общаться с агентом. Он просто должен это делать.
12) Агент как Stateless Reducer. На входе — состояние и запрос. На выходе — новое состояние и ответ. Всё как в хорошем Redux. Никакого собственного внутреннего состояния, он должен работать как чистая функция

Бонус:
13) Предзагрузи все необходимое. Агент не должен постоянно дёргать одни и те же данные. Наполняй контекст тем, что почти наверняка пригодится.

Репа: https://github.com/humanlayer/12-factor-agents
Доклад: https://www.youtube.com/watch?v=8kMaTybvDUw