12 因子智能体 - 构建可靠的大语言模型（LLM）应用程序的原则

秉承 12 因子应用 的精神。本项目的源代码公开于 https://github.com/humanlayer/12-factor-agents，欢迎提供反馈和贡献。让我们一起解决这个问题！

[!TIP] 错过了 AI 工程师世界博览会？在此观看演讲

正在寻找上下文工程（Context Engineering）相关内容？直接跳转到第 3 因子

想要为 npx/uvx create-12-factor-agent 做贡献？请查看 讨论线程

你好，我是 Dex。我已经 钻研 AI 智能体 有一段时间了 (链接)。

我尝试过市面上所有的智能体框架，从即插即用（plug-and-play）的 crew/langchains，到“极简主义”的 smolagents，再到“生产级”的 langraph、griptape 等等。

我和许多非常优秀的创始人交谈过，无论是在 YC 内部还是外部，他们都在用 AI 构建令人印象深刻的事物。大多数人都是自己从头搭建技术栈（rolling the stack）。我在面向客户的生产环境中很少看到很多现成的框架。

令我惊讶的是，大多数自称是"AI 智能体”的产品其实并没有那么具备代理能力（agentic）。它们大多是确定性代码，只是在恰到好处的地方点缀了一些 LLM 步骤，以使体验真正变得神奇。

至少好的智能体不会遵循 "这是你的提示词，这是一堆工具，循环直到达成目标" 的模式。相反，它们主要由软件组成。

因此，我决定回答这个问题：

我们可以使用哪些原则来构建真正足够好、可以交付给生产环境客户的大语言模型（LLM）驱动的软件？

欢迎来到 12 因子智能体。正如自戴利（Daley）以来的每一位芝加哥市长一致在城市主要机场张贴的那样，很高兴你来到这里。

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

简版：12 个因子

即使 LLM 继续以指数级变得更强大，仍有一些核心工程技术能使 LLM 驱动的软件更可靠、更具可扩展性且更易维护。

• 我们如何走到这一步：软件简史
• 因子 1：自然语言到工具调用
• 因子 2：掌控你的提示词
• 因子 3：掌控你的上下文窗口
• 因子 4：工具只是结构化输出
• 因子 5：统一执行状态与业务状态
• 因子 6：通过简单 API 启动/暂停/恢复
• 因子 7：通过工具调用联系人类
• 因子 8：掌控你的控制流
• 因子 9：将错误紧凑化至上下文窗口
• 因子 10：小型、专注的智能体
• 因子 11：随处触发，在用户所在之处与他们相遇
• 因子 12：让你的智能体成为无状态归约器

视觉导航

我们是如何走到这一步的

为了更深入地了解我的智能体之旅以及我们是如何走到这一步的，请查看 软件简史 - 这里有一个快速摘要：

智能体的承诺

我们将要谈论很多关于有向图 (DGs) 及其无环的朋友，即 有向无环图 (DAGs)。我首先要指出的是……嗯……软件本质上就是一个有向图。我们过去用流程图来表示程序是有原因的。

从代码到 DAGs

大约 20 年前，我们开始看到 DAG 编排器变得流行。我们说的是经典之作，如 Airflow、Prefect，一些前身，以及一些较新的项目，如 (dagster、inggest、windmill)。这些遵循相同的图模式，并增加了可观测性、模块化、重试、管理等好处。

智能体的承诺

我不是第一个说过这话的人，但我刚开始学习智能体时最大的收获是，你可以直接把 DAG 扔掉。与其让软件工程师编写每一个步骤和边界情况，你可以给智能体一个目标和一组转换：

然后让 大语言模型 (LLM) 实时做出决策来找出路径

这里的承诺是，你写的软件更少，你只需要给 LLM 图的“边”，让它去找出节点。你可以从错误中恢复，你可以写更少的代码，你可能会发现 LLM 能找到解决问题的新颖方案。

智能体即循环

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

让我们再深入一步——有了智能体，你就有了一个由 3 个步骤组成的循环：

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

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 选择下一步（工具）或确定我们已完成。

这是一个多步骤示例：

GIF 版本

为什么是 12 因子智能体（Agents）？

归根结底，这种方法并没有达到我们预期的效果。

在构建 HumanLayer 的过程中，我至少与 100 位 SaaS 构建者（SaaS Builders，主要是技术创始人）交谈过，他们希望让自己的现有产品更具智能体（Agent）特性。这段旅程通常如下所示：

1. 决定要构建一个智能体（Agent）
2. 产品设计、用户体验（UX）映射、确定要解决的问题
3. 想要快速推进，所以直接拿取 $FRAMEWORK 并开始构建
4. 达到 70-80% 的质量标准
5. 意识到对于大多数面向客户的功能来说，80% 还不够好
6. 意识到要突破 80% 需要逆向工程框架（Framework）、提示词（Prompts）、流程等
7. 从头再来

随机免责声明

免责声明：我不确定确切该在哪里说这个，但这里似乎和哪里一样好：这绝非意在贬低现有的众多框架（Frameworks），或是那些非常聪明的工作于其上的人们。它们实现了不可思议的事情，并加速了 AI 生态系统的发展。

我希望这篇文章的一个成果是，智能体框架的构建者能从我和其他人的经历中学习，使框架变得更好。

特别是对于那些想要快速推进但又需要深度控制的构建者而言。

免责声明 2：我不会谈论 MCP。我相信你能看出它放在哪里合适。

免责声明 3：我主要使用 TypeScript，出于某些原因，但这所有内容在 Python 或你喜欢的任何其他语言中都能工作。

总之，回到正题……

优秀大语言模型（LLM）应用的设计模式

在钻研了数百个 AI 库并与数十位创始人合作后，我的直觉是这样的：

1. 有一些核心要素能让智能体（Agent）变得出色
2. 完全押注一个框架（Framework），并构建本质上属于从零开始的重写，可能会适得其反
3. 有一些核心原则能让智能体（Agent）变得出色，如果你引入一个框架，你将获得其中大部分/全部
4. 但是，我所见过的构建者将高质量 AI 软件交付给客户的最快途径，是从智能体构建中提取小型、模块化的概念，并将它们整合到现有产品中
5. 这些来自智能体（Agent）的模块化概念可以由大多数熟练的软件工程师定义和应用，即使他们没有 AI 背景

我所见过的构建者将优质 AI 软件交付给客户的最快途径，是从智能体构建中提取小型、模块化的概念，并将它们整合到现有产品中

12 因子（再次）

• 我们如何走到这一步：软件简史
• 因子 1：自然语言到工具调用
• 因子 2：掌控你的提示词（Prompts）
• 因子 3：掌控你的上下文窗口（Context Window）
• 因子 4：工具只是结构化输出
• 因子 5：统一执行状态和业务状态
• 因子 6：通过简单 API 启动/暂停/恢复
• 因子 7：通过工具调用联系人类
• 因子 8：掌控你的控制流（Control Flow）
• 因子 9：将错误紧凑化到上下文窗口
• 因子 10：小型、专注的智能体（Agents）
• 因子 11：从任何地方触发，在用户所在处相遇
• 因子 12：让你的智能体（Agent）成为无状态归约器（Stateless Reducer）

荣誉提名 / 其他建议

• 因子 13：预取你可能需要的所有上下文

相关资源

• 在此 贡献本指南
• 我在 Tool Use 播客的一期节目中谈到了很多相关内容（2025 年 3 月）
• 我在 The Outer Loop 上撰写了一些相关内容
• 我与 @hellovai 一起举办关于 最大化 LLM（大语言模型）性能 的网络研讨会
• 我们使用此方法论构建 开源 (OSS) 智能体 (Agent)
• 我们无视了所有自己的建议，并构建了一个用于在 Kubernetes（容器编排系统）中运行分布式智能体 (Agent) 的框架
• 本指南的其他链接：
  • 12 因子应用
  • 构建有效的智能体 (Anthropic)
  • 提示词即函数
  • 库模式：为什么框架是邪恶的
  • 错误的抽象
  • Mailcrew 智能体 (Agent)
  • Mailcrew 演示视频
  • Chainlit 演示
  • 面向 LLM（大语言模型）的 TypeScript
  • 模式对齐解析
  • 函数调用与结构化输出及 JSON 模式对比
  • GitHub 上的 BAML
  • OpenAI JSON 与函数调用
  • 外环智能体 (Agent)
  • Airflow
  • Prefect
  • Dagster
  • Inngest
  • Windmill
  • AI 智能体索引 (MIT)
  • NotebookLM 关于寻找模型能力边界

贡献者

感谢所有为 12-factor 智能体 (Agent) 做出贡献的人！

许可证

所有内容和图片均根据 CC BY-SA 4.0 许可协议 授权

代码根据 Apache 2.0 许可协议 授权

12-Factor Agents 快速上手指南

12-Factor Agents 是一套基于 12-Factor Apps 原则构建可靠 LLM 应用的方法论与工具集。它旨在帮助开发者构建生产级、可扩展且易于维护的 AI Agent 系统，强调将软件工程的最佳实践应用于大模型应用开发中。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: macOS / Linux / Windows
• 运行时:
  • Node.js (推荐 v16+)：用于通过 npx 运行工具。
  • Python (推荐 3.10+)：用于通过 uvx 运行工具。
• 包管理工具:
  • npm (随 Node.js 安装)
  • uv (Python 包管理器，需单独安装)
• 版本控制: git

安装步骤

本项目主要通过命令行工具进行初始化，同时也提供完整的文档仓库供参考。

方式一：使用 CLI 初始化（推荐）

如果您希望快速创建一个符合 12-Factor 规范的项目骨架，可以使用以下命令之一：

# 使用 npm
npx create-12-factor-agent

# 或使用 uv (Python 生态)
uvx create-12-factor-agent

方式二：克隆完整仓库

如果您需要查阅所有 12 个因子（Factors）的详细原理和最佳实践，建议直接克隆源代码仓库：

git clone https://github.com/humanlayer/12-factor-agents
cd 12-factor-agents

基本使用

1. 启动项目

执行安装步骤中的 CLI 命令后，按照提示输入项目名称和配置，即可生成基础项目结构。生成的项目将包含遵循 12-Factor 原则的代码模板。

2. 理解核心概念

本项目的核心理念是避免简单的“循环调用”，而是构建由软件主导的确定性流程。以下是项目中展示的基础 Agent 循环逻辑示例：

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)

3. 阅读核心文档

项目详细定义了构建可靠 LLM 应用的 12 个关键因子，建议按顺序阅读以深入理解架构设计：

• Factor 1: Natural Language to Tool Calls (自然语言到工具调用)
• Factor 2: Own your prompts (掌控你的提示词)
• Factor 3: Own your context window (掌控上下文窗口)
• Factor 4: Tools are just structured outputs (工具即结构化输出)
• Factor 5: Unify execution state and business state (统一执行状态与业务状态)
• Factor 6: Launch/Pause/Resume with simple APIs (通过简单 API 启动/暂停/恢复)
• Factor 7: Contact humans with tool calls (通过工具调用联系人类)
• Factor 8: Own your control flow (掌控控制流)
• Factor 9: Compact Errors into Context Window (将错误压缩进上下文窗口)
• Factor 10: Small, Focused Agents (小型、专注的 Agent)
• Factor 11: Trigger from anywhere, meet users where they are (随处触发，适应用户)
• Factor 12: Make your agent a stateless reducer (让 Agent 成为无状态归约器)

通过以上步骤，您可以快速搭建起一个符合工业级标准的 AI Agent 应用原型。