12-Factor Agents: как строить надёжные LLM-агенты
Dex Horthy из HumanLayer опубликовал методологию 12-Factor Agents — 12 принципов создания надёжных LLM-агентов, готовых к боевому использованию.
12-Factor Agents: как строить надёжные LLM-агенты для продакшена
Dex Horthy, основатель HumanLayer, опубликовал открытый гайд 12-Factor Agents — набор из 12 инженерных принципов для создания LLM-приложений, которые реально работают у клиентов. В начале 2025 года Horthy дистиллировал свой опыт в руководство, представленное на AI Engineer World’s Fair и теперь доступное в виде популярного GitHub-репозитория. Методология уже вызвала широкое обсуждение в сообществе: гайд быстро попал на первую страницу Hacker News, набрал тысячи звёзд на GitHub и спровоцировал дискуссию о том, как правильно строить AI-native приложения.
Откуда взялась проблема
Большинство продуктов, позиционирующих себя как «AI Agents», на деле вовсе не такие агентивные — это преимущественно детерминированный код, в котором шаги с LLM расставлены в нужных местах, чтобы создать ощущение магии.
«Хорошие агенты не следуют паттерну “вот твой промпт, вот набор инструментов, крути цикл пока не достигнешь цели”. Они в основном просто программный код.»
В процессе создания HumanLayer Horthy пообщался как минимум со 100 SaaS-строителями (преимущественно техническими основателями), которые хотели сделать свои продукты более агентивными. Команды брали агентный фреймворк, чтобы быстро двигаться, достигали 70–80% нужного функционала, а затем упирались в потолок: агент начинал галлюцинировать шаги, зацикливаться или иным образом выходить за рамки допустимой надёжности. Преодоление этой отметки требовало копаться в кишках фреймворка.
Как устроен агентный цикл (и почему он не работает сам по себе)
Типичный цикл агента выглядит так:
const initial_event = { message: "..." };
let context = [initial_event];
while (true) {
const next_step = await llm.determine_next_step(context);
context.push(next_step);
if (next_step.intent === "done") return next_step.final_answer;
const result = await execute_step(next_step);
context.push(result);
}
Начальный контекст — это стартовое событие (сообщение пользователя, срабатывание cron, вебхук и т.д.), и мы просим LLM выбрать следующий шаг (инструмент) или определить, что задача выполнена. Большинство разработчиков быстро отказываются от идеи «бесконечного цикла вызовов инструментов», когда видят, что более 10–20 ходов превращаются в запутанный хаос, из которого LLM не может выбраться.
graph TD
A[Стартовое событие] --> B[LLM определяет следующий шаг]
B --> C{Цель достигнута?}
C -- Да --> D[Финальный ответ]
C -- Нет --> E[Выполнить шаг / инструмент]
E --> F[Результат → в контекст]
F --> B
B --> G[Ошибка / зацикливание]
G -.-> H[Агент ломается]
12 факторов: краткий обзор
Даже если LLM продолжают экспоненциально мощнеть, существуют базовые инженерные техники, которые делают LLM-powered software надёжнее, масштабируемее и проще в поддержке.
| № | Фактор | Суть |
|---|---|---|
| 1 | Natural Language to Tool Calls | LLM переводит текст в структурированный JSON для вызова инструментов |
| 2 | Own your prompts | Промпты — это код. Полный контроль без «чёрных ящиков» фреймворков |
| 3 | Own your context window | Context window — не хранилище, а бюджет внимания |
| 4 | Tools are just structured outputs | Инструменты — просто типизированный вывод LLM |
| 5 | Unify execution state and business state | Единое состояние для выполнения и бизнес-логики |
| 6 | Launch/Pause/Resume with simple APIs | Агент должен уметь ставиться на паузу и возобновляться |
| 7 | Contact humans with tool calls | Human-in-the-loop — первоклассная операция, не edge case |
| 8 | Own your control flow | Явные пути выполнения, никакого делегирования |
| 9 | Compact Errors into Context Window | Ошибки → компактное представление в контексте для самоисправления |
| 10 | Small, Focused Agents | Один агент — одна задача. 3–20 шагов максимум |
| 11 | Trigger from anywhere | Один код — любой триггер: Slack, API, cron, вебхук |
| 12 | Make your agent a stateless reducer | Агент как чистая функция: f(events) → next_action |
Самые важные факторы на практике
Factor 3: Владей своим context window
Context window — это не просто хранилище. Это бюджет внимания модели. Horthy проанализировал 100 000 сессий разработчиков и выявил «зону тупости» (dumb zone): средние 40–60% большого контекстного окна, где recall модели деградирует, а рассуждения начинают ломаться. После заполнения 40% контекста отдача стремительно падает.
Factor 10: Маленькие, сфокусированные агенты
Агент должен быть ограничен 3–20 шагами. Для сложных задач несколько «Micro-Agents» соединяются вместе в детерминированный DAG (направленный ациклический граф).
Factor 7: Люди — через tool calls
Языковые модели, управляющие чётко ограниченными наборами задач, позволяют легко интегрировать живую обратную связь от пользователей, превращая её в шаги рабочего процесса без ухода в петли контекстных ошибок.
Не фреймворки, а принципы
Многие успешные AI-продукты не используют готовые агентные фреймворки вовсе — вместо этого они берут несколько модульных техник из «агентного» подхода и встраивают их в собственный стек.
Будущее разработки агентов — не в более «магических» фреймворках, а в качественной инженерии, применённой к возможностям LLM. Агенты — это программный код. Относитесь к ним соответственно, и они вознаградят надёжностью и maintainability.
Сосредотачиваясь на базовых паттернах (stateless reducers, unified state), вы можете менять LLM-провайдеров или библиотеки без переписывания бизнес-логики.
Значение для отрасли
Методология уже оказала влияние за пределами сообщества разработчиков. Даже авторы популярных фреймворков приняли эти уроки к сведению. Команда LangChain, например, рекомендовала 12-Factor Agents как обязательное чтение, отметив, что многие тезисы Horthy сводятся к лучшему «context engineering» и контролю разработчика.
Наиболее успешные команды, поставляющие AI в enterprise, избегают тяжёлых orchestration-фреймворков в пользу кастомных циклов, построенных на простых примитивах.
Репозиторий открыт для вклада сообщества: https://github.com/humanlayer/12-factor-agents