humanlayer/12-factor-agents — 构建生产级 LLM Agent 的 12 条原则，20.6k ⭐（今日 +399）

humanlayer/12-factor-agents — 构建生产级 LLM Agent 的 12 条原则

GitHub: https://github.com/humanlayer/12-factor-agents Stars: 20,643 ⭐（今日 +399 🔥） 作者: HumanLayer 团队 定位: LLM 驱动生产软件的 12 条设计原则

核心理念

受经典「The Twelve-Factor App」启发，12-factor-agents 为 LLM Agent 系统提供了一套类似的工程原则。如果说 12-Factor App 解决了云原生应用的可移植性和可扩展性问题，12-factor-agents 则解决了 Agent 系统的可靠性和可维护性问题。

12 条原则

I. 自然语言到工具调用（Natural Language → Tool Calls） Agent 的核心能力是将自然语言意图转化为精确的工具调用，而非生成文本。

II. 拥抱小模型（Own Your Prompts） 通过精心设计的 prompt 和小模型，往往比依赖大模型更可靠、更经济。

III. 人机协作循环（Human-in-the-Loop） 关键决策点必须设计人工介入机制，不能完全自动化。

IV. 统一执行状态（Unified Execution State） Agent 状态必须可序列化、可持久化，支持暂停和恢复。

V. 工具即合约（Tools as Contracts） 工具接口是 Agent 与外部世界的边界，必须明确定义和版本化。

VI. 幂等性优先（Idempotency First） 所有 Agent 动作应设计为幂等，支持安全重试。

VII. 最小权限原则（Minimal Footprint） Agent 只请求完成当前任务所需的最小权限。

VIII. 可观测性内置（Built-in Observability） 每个 Agent 动作必须可追踪、可审计、可重放。

IX. 明确终止条件（Explicit Termination） Agent 必须有清晰的成功/失败终止条件，避免无限循环。

X. 优雅降级（Graceful Degradation） 当工具调用失败时，Agent 应有明确的降级策略。

XI. 上下文窗口管理（Context Window Management） 主动管理上下文窗口，避免信息丢失和 Token 浪费。

XII. 配置与代码分离（Config vs Code） Agent 行为参数（模型选择、工具列表、系统提示）与业务逻辑代码分离。

为何重要

大多数 Agent 教程教你「如何让 Agent 跑起来」，但很少告诉你「如何让 Agent 在生产环境可靠运行」。12-factor-agents 填补了这一空白，是从原型到生产的关键思维框架。

20.6k star 显示工程师社区对这类系统化工程原则的强烈需求。