12 Factor Agents - 建構可靠LLM應用的12個原則

概述

12 Factor Agents 是一套建構可應用於生產環境的LLM驅動軟體的原則方法論，由 Dex Horthy 和 HumanLayer 團隊開發。

背景與動機

為何需要這套原則？

作者在與100多位SaaS建構者（主要是技術創始人）交流後發現，大多數AI Agent開發都會遇到「70-80%品質瓶頸」：

1. 初期快速進展：使用現有框架快速達到70-80%的功能
2. 品質瓶頸：發現80%對於面向客戶的功能還不夠好
3. 框架限制：要突破80%需要逆向工程框架、提示詞、流程等
4. 從頭開始：最終不得不拋棄框架重新開始

核心洞察

• 大多數成功的生產級「AI Agent」實際上並不那麼「智能體化」
• 它們主要是精心設計的軟體系統，在關鍵點巧妙地使用LLM
• 最快讓客戶使用高品質AI軟體的方法是採用小而模組化的概念，並將其整合到現有產品中

12個核心原則

Factor 1: Natural Language to Tool Calls

自然語言轉換為工具呼叫

LLM的核心超能力是將自然語言轉換為結構化資料（JSON）。一切Agent操作都應該從這個基礎轉換開始。

// 核心模式
const response = await llm.generateToolCall(userMessage, availableTools);
// response 是結構化的 JSON，不是自由文本

Factor 2: Own your prompts

擁有你的提示詞

將提示詞視為關鍵的、版本控制的程式碼資產，而不是一次性輸入。

• 在應用程式程式碼庫中管理提示詞
• 支援系統性測試、部署和回滾
• 確保一致性、可重現性和可控演進

Factor 3: Own your context window

擁有你的上下文視窗

主動並有意地管理LLM的上下文視窗。

• 確保上下文視窗只包含與當前任務直接相關的資訊
• 修剪不必要的資料以防止「上下文漂移」
• 提高LLM效能，減少token使用

Factor 4: Tools are just structured outputs

工具就是結構化輸出

將「工具」視為LLM輸出的結構化JSON，並進行驗證。

// 工具呼叫只是JSON schema驗證
const toolCall = validateToolCall(llmOutput, toolSchema);
const result = await executeValidatedTool(toolCall);

Factor 5: Unify execution state and business state

統一執行狀態和業務狀態

確保LLM的內部「執行狀態」與應用程式的實際「業務狀態」保持一致。

• 防止LLM基於過時或錯誤資訊操作
• 避免幻覺或無效操作
• 將執行狀態持久化在業務狀態旁邊

Factor 6: Launch/Pause/Resume with simple APIs

透過簡單API啟動/暫停/恢復

設計具有清晰程式設計介面的LLM代理，支援生命週期管理。

interface AgentControl {
  launch(config: AgentConfig): Promise<AgentInstance>;
  pause(instanceId: string): Promise<void>;
  resume(instanceId: string): Promise<void>;
}

Factor 7: Contact humans with tool calls

透過工具呼叫聯繫人類

將人類互動作為一等公民的工具呼叫來處理。

• 高風險步驟路由給人類審核
• 人類回饋作為結構化輸入返回系統
• 無縫的人機協作流程

Factor 8: Own your control flow

擁有你的控制流

將控制流保持在普通程式碼或自己的工作流引擎中。

• 運行顯式的OODA循環（觀察-定向-決策-行動）
• 使用收斂啟發式而不是巢狀提示
• 避免讓LLM管理複雜的控制流

Factor 9: Compact Errors into Context Window

將錯誤壓縮到上下文視窗

將錯誤資訊壓縮到下一個提示中以關閉回饋循環。

• 讓LLM能夠從錯誤中學習和恢復
• 提供結構化的錯誤資訊
• 支援自我修復能力

Factor 10: Small, Focused Agents

小而專注的Agent

建構小型、單一用途的代理，而不是龐大的單體聊天機器人。

// 好的做法：專注的小Agent
class EmailSummaryAgent {
  async summarize(email: Email): Promise<Summary> { /* ... */ }
}

class PriorityClassificationAgent {
  async classify(email: Email): Promise<Priority> { /* ... */ }
}

Factor 11: Trigger from anywhere, meet users where they are

從任何地方觸發，在使用者所在的地方提供服務

從使用者已經工作的地方觸發代理：CLI、webhook、cron等。

• 整合到現有工作流程
• 多種觸發機制
• 使用者友好的存取點

Factor 12: Make your agent a stateless reducer

讓你的Agent成為無狀態的reducer

應用程式管理狀態，Agent保持無狀態。

// 無狀態Agent模式
class StatelessAgent {
  step(state: State): Promise<State> {
 
  }
}

技術架構模式

核心循環簡化

每個Agent本質上都歸結為：

const prompt = "Instructions for next step selection";
const switchFunction = (json) => routeToFunction(json);
const context = manageWhatLLMSees();
const loop = whileNotDone();

與傳統DAG的區別

• 傳統DAG：軟體工程師編碼每個步驟和邊緣情況
• Agent方法：給Agent一個目標和一組轉換，讓LLM即時決策路徑
• 實際情況：最成功的實現是在更大的確定性DAG中巧妙地使用Agent模式

適用場景

最適合的場景

• 需要自然語言理解的結構化任務
• 需要人機協作的工作流程
• 複雜的多步驟業務流程
• 需要高可靠性的生產環境

不適合的場景

• 簡單的確定性任務（直接寫程式碼更好）
• 需要100%準確性的關鍵任務
• 資源極度受限的環境

實現建議

漸進式採用

1. 從小處開始：選擇一個與當前挑戰相關的原則
2. 實施並觀察：看到改進效果
3. 逐步添加：然後添加另一個原則
4. 持續優化：不斷完善和調整

技術棧推薦

• 語言：TypeScript（作者推薦，也支援Python等其他語言）
• 關鍵庫：BAML（用於schema對齊解析）
• 部署：支援雲原生和Kubernetes

相關資源

官方資源

• GitHub倉庫
• HumanLayer官網
• The Outer Loop部落格

擴展閱讀

• Building Effective Agents (Anthropic)
• 12 Factor Apps原始方法論
• Function Calling vs Structured Outputs vs JSON Mode

總結

12 Factor Agents提供了一個系統性的方法來建構真正可應用於生產環境的LLM應用。它強調的不是建立更神奇的框架，而是將更好的軟體工程實踐應用於LLM能力。記住核心理念：Agent就是軟體，按軟體來對待它們，它們會以可靠性、可維護性和競爭對手無法匹敵的能力回報你。