12因子Agent原则
构建可靠、可扩展、可维护的LLM应用的核心工程原则。
- Star 数
- ★ 27k
- 最近更新
- 1 年前
- License
- NOASSERTION
- 主语言
- TypeScript
- FA 评分
- 24/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台
- 费用
- 免费，无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 典型场景
- 技术创始人或工程师正在设计一个生产级 Agent，希望避免常见框架的陷阱，可以参考这些原则来架构自己的系统。
- 不适合
- 希望直接安装运行、开箱即用的团队，本仓库只有文档没有可执行代码
- 需要现成框架或 API 来集成、不想自己实现这些原则的开发者
- 主要使用 Python 且需要完整 Python 示例的团队，示例以 TypeScript 为主
这个 Agent 能做什么，适合哪些场景？
12-Factor Agents 是一套指导原则，参考了经典的 12-Factor App 方法论，用于构建适合生产环境使用的 LLM 应用。仓库包含 12 个核心原则的详细内容，涵盖自然语言到工具调用、提示词管理、上下文窗口控制、工具结构化输出、状态统一、暂停/恢复、人工介入、控制流、错误压缩、小型专注 Agent、多端触发以及无状态 reducer 等主题。此外，还提供了“简要软件历史”和“附录 13：预取上下文”等补充章节。项目以 CC BY-SA 4.0 授权内容，Apache 2.0 授权代码，欢迎社区贡献。该指南强调将 Agent 构建中的模块化概念融入现有产品，而非全面采用框架。
该仓库主要提供一份分章节的指南（Markdown 格式），详细阐述 12 个原则，每个原则都包含具体的设计模式、代码示例（主要使用 TypeScript）以及架构建议。例如，Factor 1 阐述如何将自然语言指令转化为工具调用；Factor 2 强调提示词的自有与版本管理；Factor 3 讨论如何拥有和控制上下文窗口；Factor 4 指出工具只是结构化输出；Factor 5 提议统一执行状态和业务状态；Factor 6 建议使用简单 API 实现启动/暂停/恢复；Factor 7 讨论使用工具调用来联系人类；Factor 8 强调自有控制流；Factor 9 建议将错误压缩到上下文中；Factor 10 提倡小而专注的 Agent；Factor 11 讨论从任何地方触发，满足用户所在；Factor 12 建议将 Agent 设计为无状态 reducer。仓库不包含可执行代码，而是纯粹的知识性内容，为 LLM 应用架构提供指导。
- 技术创始人或工程师正在设计一个生产级 Agent，希望避免常见框架的陷阱，可以参考这些原则来架构自己的系统。
- 团队已经在使用某个 Agent 框架，但发现难以调试或扩展，可以借鉴这些原则来调整或替换框架。
- 开发者希望将 LLM 功能集成到现有产品中，可以参考如何模块化地融入 Agent 概念，而不是全盘重构。
- 架构师在规划 LLM 应用的执行状态管理，可以学习如何统一执行状态和业务状态，提高可靠性。
- 工程师需要设计长时间运行的任务处理机制，可以参考第 6 条原则的启动/暂停/恢复模式，以及第 12 条的无状态 reducer 设计。
- 团队希望让 Agent 与人工协作，可参考第 7 条原则，通过工具调用联系人类，实现人机协同。
如何安装或部署这个 Agent？
该仓库是知识库，非软件包，无需安装。可直接通过浏览器访问 GitHub 页面阅读。
如何使用这个 Agent？
使用方式：直接在 GitHub 仓库浏览 content/ 目录下的各个 factor 文件，或使用 README 中的视觉导航链接。也可以克隆仓库到本地查看。
这个 Agent 有哪些优点和局限？
- 提供了可操作的设计模式，而非抽象理论，每个原则都有详细的解释和代码示例。
- 强调模块化，而非全盘采用框架，使现有产品可以逐步集成 LLM 功能。
- 独立于特定框架或语言，以 TypeScript 示例为主，但适用于任何编程语言。
- 社区驱动，欢迎贡献和反馈，持续演进。
- 仓库是纯文档，不含任何可直接运行的代码或工具，需要读者自行实现。
- 没有具体的代码库或 API 供集成，需要自行将原则转化为实际代码。
- 未提及 MCP 等现代标准，可能不完全覆盖所有生态。
- 示例主要使用 TypeScript，可能对 Python 开发者不够友好，尽管中提到同样适用于 Python。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| 12因子Agent原则 当前 | 24 · 缺口较多 | 代码库 / SDK免费 | ★ 27k | 1 年前 | TypeScript | — |
| Claude Code 系统提示词研究 | 35 · 缺口较多 | 代码库 / SDK | ★ 2.6k | 6 个月前 | — | Claude Code |
| LangChain 与 LangGraph 智能体实战课 | 32 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 1.7k | 4 天前 | — | — |
| Dify | 55 · 缺口较多 | 自托管服务免费版 + 付费版 | ★ 159k | 今天 | Python | OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示仓库主要是一个原则性指南，没有实际代码或运行时行为。因此，所有信任标准均未得到满足：没有最小权限、用户确认、数据流透明、敏感数据处理、依赖安全、外部影响、回滚或来源归属的证据。扣分：这些方面完全缺失。
自一致性：README 中列出的 12 个因素与内容文件一致，但未提供完整内容，因此仅部分支持。依赖可用性：未提供依赖信息。失败消息：测试文件显示 CLI 对错误输入有清晰的错误消息，但未提供实际代码，因此仅部分支持。扣分：依赖可用性缺失，失败消息仅从测试推断。
受众和场景：README 明确针对构建生产级 LLM 应用的开发者，并提供了多种场景。能力边界：指南讨论了框架的局限性，但未明确说明自身边界。触发精度：未涉及。环境适配：提到 TypeScript 和 Python，但未提供具体环境要求。扣分：触发精度缺失，能力边界和环境适配仅部分覆盖。
信息架构：README 提供了清晰的结构和导航。安装说明：未提供。命名稳定性：因素名称一致，但未提供版本信息。示例和 FAQ：提供了示例和链接，但未提供 FAQ。已知限制：讨论了框架的局限性，但未明确说明自身限制。许可证：提供了 Apache 2.0 和 CC BY-SA 4.0。版本控制和变更日志：未提供。维护责任：列出了贡献者，但未明确维护者。扣分：安装说明、版本控制、变更日志缺失，其他部分仅部分覆盖。
输出可用性：指南提供了可操作的见解，但未提供实际代码或工具。边际价值：提供了独特的视角，但未提供实现。成本效益：未提供成本分析。扣分：输出可用性和成本效益仅部分支持，边际价值有支持但未量化。
声明可追溯性：README 中的声明部分有链接支持，但未提供完整证据。跨来源佐证：未提供。事实与推断分离：指南区分了个人经验和一般原则，但未明确标注。扣分：跨来源佐证缺失，其他部分仅部分支持。
- 源码中未见：最小权限约束只授予完成任务所需的权限：用专用账号或只读令牌，并限定可访问的目录和仓库。
- 源码中未见：执行前用户确认开启或自行加上执行前确认；先在沙箱或测试环境跑通，确认行为后再接入真实数据。
- 源码中未见：数据流向说明运行时观察它连接了哪些外部服务（代理或防火墙日志）；弄清数据去向之前不要输入敏感数据。
- 源码中未见：敏感信息处理使用专用、低权限、可随时吊销的 API 密钥，不要复用生产凭据，也不要让密钥出现在日志里。
- 源码中未见：依赖安全审查安装前固定版本并做一次依赖扫描（如 npm audit、pip-audit）；优先放在容器里运行。
- 源码中未见：外部影响披露先弄清它会写入、发送或修改哪些外部系统，用测试账号或测试仓库验证后再接入正式环境。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 源码中未见：来源归属可核验从官方仓库或包源安装，核对发布者和仓库地址，避免同名仿冒包。
- 仓库主要是原则性指南，没有实际代码或可执行产品，因此无法评估运行时行为。
- 未提供安装说明、版本控制或变更日志，可能影响可维护性。
- 依赖安全、数据流透明等信任方面完全缺失，需谨慎对待。