В 2011 году инженеры Heroku опубликовали документ под названием «12-Factor App». Это не код и не фреймворк, а методология — о том, как создавать масштабируемые и поддерживаемые SaaS-приложения.
Позже этот документ стал де-факто стандартом эпохи cloud-native. Docker, Kubernetes и различные микросервисные фреймворки в своей основе несут гены 12-Factor.
Теперь кто-то решил сделать то же самое для AI-агентов.
humanlayer/12-factor-agents: 21 600 звёзд, 273 коммита. Автор Dex пишет прямо:
Я перепробовал каждый агентный фреймворк — от готовых к использованию CrewAI и LangChain до позиционируемых как «минималистичные» SmolAgents и заявляющих о «промышленном уровне» LangGraph и Griptape. Но большинство продуктов, называющих себя «AI-агентами», на самом деле не обладают настоящей агентностью. По большей части это детерминированный код, в который просто в нужных местах добавили немного LLM.
Звучит резко, но если вдуматься, это действительно так.
Ключевая идея: хороший агент — это не «задай цель и пусть работает сам»
Первый принцип 12-Factor Agents переворачивает представления многих об агентах:
Factor 1: Natural Language to Tool Calls
Основная способность LLM — не «мышление», а преобразование естественного языка в структурированные вызовы инструментов. Это означает, что фокус при проектировании агента должен смещаться на «предоставление правильных инструментов» и «определение корректного формата вызовов», а не на то, чтобы заставлять LLM блуждать в бесконечной свободе.
Factor 8: Own your control flow（掌控你的控制流）
Этот принцип ещё важнее. Многие пишут агентов по схеме: «дай промпт, дай набор инструментов, крути цикл до завершения». 12-Factor чётко заявляет: так нельзя.
В агентах, готовых к промышленной эксплуатации, поток выполнения должен определяться разработчиком: какие шаги детерминированы, какие можно доверить LLM, когда требуется вмешательство человека и как откатываться при ошибках. LLM — это двигатель, но руль должен оставаться у вас.
Краткий обзор 12 принципов
Эти 12 принципов охватывают все аспекты разработки агентов:
- Factor 1-4 описывают базовую логику «вызовов инструментов»: естественный язык → структурированный вывод → управление контекстом → определение инструментов
- Factor 5-7 касаются «состояния выполнения»: как единообразно управлять бизнес-состоянием и состоянием выполнения, как приостанавливать/возобновлять работу, как привлекать человека
- Factor 8-10 относятся к «архитектурному проектированию»: принадлежность потока управления, сжатие ошибок, гранулярность агента
- Factor 11-12 охватывают «интеграцию и развёртывание»: запуск из любого места, превращение агента в stateless-редьюсер
Я выделил несколько наиболее практичных принципов, чтобы разобрать их отдельно.
Factor 3: Own your context window（掌控你的上下文窗口）
Контекстное окно не бесконечно. 12-Factor подчёркивает, что контекстом необходимо управлять стратегически: какую информацию сохранять, какую сжимать, а какую удалять. В противном случае по мере удлинения диалога производительность LLM будет резко падать.
Factor 7: Contact humans with tool calls（用工具调用联系人类）
Этот принцип очень практичен. Когда агент сталкивается с неоднозначной ситуацией, он не должен «гадать», а должен использовать вызов инструментов для запроса вмешательства человека. Звучит просто, но большинство агентных фреймворков не проектируют это как первоклассную функцию.
Factor 12: Make your agent a stateless reducer（让 Agent 成为无状态的 reducer）
Возможно, это самый «инженерный» принцип. Представьте агента как функцию-редьюсер: вы передаёте ей событие и текущее состояние, а она возвращает новое состояние. Отсутствие состояния (stateless) означает возможность горизонтального масштабирования, повторных попыток и мониторинга.
Почему это руководство заслуживает внимания?
Потому что главная проблема в разработке AI-агентов сегодня заключается не в «недостаточной мощности технологий», а в том, что «методология ещё не сформирована».
Все экспериментируют, набивают шишки и изобретают велосипед заново. Ценность 12-Factor Agents в том, что он пытается систематизировать этот разрозненный опыт, превратив его в набор принципов, которые можно обсуждать, итеративно улучшать и передавать дальше.
Он не привязан ни к какому фреймворку и не рекомендует конкретный стек технологий. Он отвечает на более фундаментальный вопрос: каких принципов следует придерживаться, когда вы хотите создать на базе LLM по-настоящему рабочий продукт?
Основной источник: GitHub - humanlayer/12-factor-agents