12-factor-agents

为构建生产级LLM应用总结的12条设计原则，源自对上百个AI项目的观察和实际工程经验。每条原则都聚焦可操作性：Own your prompts、Unify execution state、Small focused agents等，帮助开发者避免框架陷阱，写出真正可靠的agent代码。当前热度高，因为直接回应了AI工程中'80%质量陷阱'的痛点，提供了模块化、可渐进应用的解决方案。

README

12-Factor Agents - 构建可靠 LLM 应用的原则

秉承 12 Factor Apps 的精神。本项目的源码位于 https://github.com/humanlayer/12-factor-agents，欢迎提供反馈和贡献。让我们一起探索！

[!TIP] 错过了 AI Engineer World's Fair？点此观看演讲

寻找 Context Engineering？直接跳转到第三因素

想为 npx/uvx create-12-factor-agent 做贡献？查看讨论帖

嗨，我是 Dex。我已经在 AI agent 上研究了一段时间。

我尝试过市面上所有的 agent 框架，从即插即用的 crew/langchains 到所谓的“极简” smolagents，再到“生产级”的 langraph, griptape 等。

我与许多非常优秀的创始人交流过，包括 YC 内部和外部的，他们都在用 AI 构建令人印象深刻的产品。大多数都是自己搭建技术栈。我在面向客户的生产级 agent 中很少看到框架的身影。

我惊讶地发现，市面上大多数标榜为“AI Agent”的产品，其自主性并不强。它们大部分是确定性代码，只是在恰到好处的地方点缀了 LLM 步骤，使体验变得真正神奇。

Agent（至少是优秀的 agent）并不遵循“这是你的 prompt，这是你的工具包，不断循环直到达成目标”的模式。它们主要由普通的软件组成。

因此，我开始寻找答案：

我们能用哪些原则来构建 LLM 驱动的软件，使其真正足够好，能够交付给生产环境中的客户使用？

欢迎来到 12-factor agents。正如戴利之后的每一位芝加哥市长都会在主要机场贴满标语那样：我们很高兴你来到这里。

特别感谢 @iantbutler01, @tnm, @hellovai, @stantonk, @balanceiskey, @AdjectiveAllison, @pfbyjy, @a-churchill 以及旧金山 MLOps 社区对本指南的早期反馈。

简版：12 个因素

即使 LLM 持续以指数级变得更强大，仍有一些核心工程技巧能让基于 LLM 的软件更可靠、更具可扩展性、更易于维护。

视觉导航

我们如何走到今天

关于我的 agent 之旅以及为何走到这里，更深度的探讨请参阅软件简史 - 这里快速总结：

agent 的承诺

我们将大量讨论有向图（Directed Graphs, DG）及其无环版本 DAG。首先需要指出的是……软件本身就是一个有向图。我们过去用流程图表示程序，这是有原因的。

010-software-dag

从代码到 DAG

大约 20 年前，DAG 编排器开始流行。比如经典的 Airflow、Prefect，一些前辈，以及一些更现代的（dagster、inggest、windmill）。它们遵循相同的图模式，并额外提供了可观测性、模块化、重试、管理等功能。

015-dag-orchestrators

agent 的承诺

我不是第一个这么说的人，但我开始学习 agent 时最大的收获是：你可以抛弃 DAG。不再需要软件工程师为每一步和边界情况编写代码，而是给 agent 一个目标和一组转换规则：

025-agent-dag

然后让 LLM 实时决策，找出路径：

026-agent-dag-lines

这里的承诺是：你写的软件更少，只需给 LLM 图的“边”，让它自己找出节点。你可以从错误中恢复，编写更少的代码，并且可能发现 LLM 能给出新颖的解决方案。

agent 作为循环

正如我们稍后会看到的，结果证明这并不完全奏效。

我们再深入一步——对于 agent，你有一个由 3 步组成的循环：

LLM 确定工作流中的下一步，输出结构化 JSON（“工具调用”）
确定性代码执行工具调用
结果被追加到上下文窗口
重复，直到下一步被确定为“完成”

initial_event = {"message": "..."}
context = [initial_event]
while True:
  next_step = await llm.determine_next_step(context)
  context.append(next_step)

  if (next_step.intent === "done"):
    return next_step.final_answer

  result = await execute_step(next_step)
  context.append(result)

我们的初始上下文就是起始事件（可能是用户消息、cron 触发器、webhook 等），然后让 LLM 选择下一步（工具），或者判断我们已经完成。

这里是一个多步示例：