项目介绍
12-Factor Agents 是由 HumanLayer 创始人 Dex Horthy 发起的一个开源项目，旨在定义构建可靠 LLM 驱动软件的工程原则。受经典《12-Factor App》启发，该项目系统地回答了：“什么原则可以让我们构建出真正能交付给生产环境客户的 LLM 驱动软件？”
项目在 GitHub 上已获得 20,894+ Star，本周增长超过 1,729 Star，成为 AI 工程领域的思想领袖之作。
项目背景
Dex Horthy 在尝试了 CrewAI、LangChain、Smolagents 等所有主流 Agent 框架后，发现了一个令人惊讶的事实：
大多数自称"AI Agent"的产品其实并不那么 Agentic。 它们大多是确定性代码，在恰到好处的节点点缀 LLM 步骤，让体验变得真正神奇。
真正的生产级 Agent 不是"给你一个提示词+一堆工具，循环直到目标达成"的模式，而是主要由常规软件构成。
核心原则 — 12 个 Factors
Factor 1: 自然语言到工具调用
将自然语言输入映射为结构化的工具调用，而非让 LLM 自由发挥。这是 Agent 可靠性的基石。
Factor 2: 拥有你的提示词
提示词是生产代码的一部分，应该像管理代码一样进行版本控制、测试和部署。
Factor 3: 拥有你的上下文窗口
精确控制进入 LLM 上下文的内容，而非将所有历史对话都塞进去。上下文工程比提示工程更重要。
Factor 4: 工具即结构化输出
将工具调用视为结构化输出的一种形式，这统一了 LLM 输出和工具调用的处理方式。
Factor 5: 统一执行状态和业务状态
将 Agent 的执行状态（当前步骤、已完成任务）与业务数据状态统一管理，避免状态割裂导致的错误。
Factor 6: 用简单 API 实现启动/暂停/恢复
Agent 工作流应该是可暂停和可恢复的，就像操作系统中的进程一样。
Factor 7: 通过工具调用联系人类
当 Agent 遇到不确定的情况时，应该通过工具调用机制联系人类审批或决策，而非自行猜测。
Factor 8-12: （更多原则）
包括可观测性、渐进式增强、容错设计等。
核心洞见
为什么框架很少用于生产？
Dex Horthy 和许多 YC 创始人的交流发现：大多数生产中的 AI 产品都在自研栈，很少使用框架。因为：
- 框架抽象层太厚，难以调试
- 框架版本更新快，兼容性差
- 生产环境需要的精细控制，框架无法提供
Agent 的正确打开方式
真正好用的 Agent 遵循"确定性代码为主，LLM 点缀为辅"的原则。90% 的代码是常规软件工程，10% 是 LLM 调用。
快速体验
# 创建 12-factor agent 项目
npx create-12-factor-agent my-agent
# 或
uvx create-12-factor-agent my-agent
结合当前技术背景的分析
2026年，AI Agent 领域正在经历"疯狂炒作 → 理性回归"的关键转折：
- 框架疲劳 — 开发者厌倦了频繁更换的 Agent 框架，开始回归"简单工具+常规代码"的模式
- 生产级需求觉醒 — 企业不再满足于 Demo 级的 Agent 演示，开始要求可靠、可维护、可调试的生产系统
- 上下文工程兴起 — 提示工程（Prompt Engineering）正在被上下文工程（Context Engineering）取代，精确控制 LLM 的输入比写好提示词更重要
12-Factor Agents 提供了思考 AI 软件工程的全新框架——不是教你用什么框架，而是教你如何思考构建 AI 应用。
更新记录（2026-05-22）
- 首次上榜 GitHub Trending，本周 +1,729 Star
- 项目获得 20,894 Star，成为 AI Agent 工程领域的必读资源