humanlayer/12-factor-agents

项目介绍

12-Factor Agents 是一份文字指南而不是代码库，它回答一个工程问题：用哪些原则才能把 LLM 驱动的软件做到可以交付给生产客户。它借用了经典 12 Factor Apps 的组织方式，核心论点是：真正成功的「智能体」大多是普通软件，只是在恰当位置插入了 LLM 调用，而不是「给模型一段提示词加一袋工具、循环到模型说完成」的写法。

内容按十二条相互独立的原则组织，另有一篇附录。涵盖的主题包括：把自然语言转成工具调用、自己掌控提示词与上下文窗口、把工具视为结构化输出、统一执行状态与业务状态、用简单 API 实现启动/暂停/恢复、通过工具调用联系人类、自己掌控控制流、把错误压缩进上下文、保持智能体小而聚焦、从任意入口触发、把智能体做成无状态 reducer。

目标读者是希望把智能体能力逐步加进现有产品的工程师或技术创始人，而不是打算采用整套框架、围绕框架重写的人。作者说明示例以 TypeScript 为主，但原则与语言无关。

快速使用

项目没有安装步骤，使用方式就是阅读。入口是 README，其中的精简条目列出了全部原则页面的链接 12-Factor Agents README。建议第一遍先读开头的软件史部分，理解朴素的 agent 循环为何撞墙，再挑与当前问题对应的原则细读。特别关注上下文构建的读者，可以直接跳到第三条讲「掌控上下文窗口」的页面 Factor 3: Own your context window。

想听讲解而非阅读的话，README 顶部给了会议演讲和更长的视频深入解读两类入口 AI Engineer 演讲、深入解读视频。另有一个讨论帖讨论参与 npx/uvx create-12-factor-agent 脚手架的工作 脚手架讨论。

使用约束

这些原则只是建议，没有任何机制去校验代码是否遵循。代码示例偏重 TypeScript，用 Python 或其他语言的读者需要自行转换示例。

仓库明确不涉及 MCP，作者将其作为有意的省略。内容与图片采用 CC BY-SA 4.0，代码采用 Apache 2.0，因此转载正文需要署名并以相同方式共享 Apache 2.0、CC BY-SA 4.0。

HotRepo 点评

该项目 2025 年 4 月以「12-factor Agents: Patterns of reliable LLM applications」登上 Hacker News，获得 475 分和 78 条评论，这个帖子是仓库最主要的实质讨论 HN 讨论。讨论基本围绕指南的核心立场展开：有评论认为模型更适合当「库」而不是「框架」，并引用了 2015 年一篇讲库模式的旧文 评论；也有人建议把底层规划循环握在自己手里，并在其中接入工作流引擎，而不是让模型维护隐式工作流 评论。关于 DSPy 如何对应「掌控提示词」这一条的提问，得到的回应更倾向于保留能打开盒子直接改提示词的能力 评论。

指南主张把智能体的小型模块化概念折进已有产品、而不是推倒重来用框架，这与上述读者的讨论方向一致，也解释了为什么这个仓库更像设计参考而非可直接运行的工具包。从 2025 年到现在它增长到约 2.7 万星；在 2026 年 11 月 8 日的 TypeScript 日榜上排在第 16 位，当天新增 26 星，这样的快照说明它保持着稳定曝光，而不是当下正处在爆发期。