AI Operations
HumanLayer 12-Factor Agents：把 LLM Agent 做成可上線軟體的 12 條工程原則
HumanLayer 的 12-Factor Agents 主張不要迷信 agent framework，而是把 prompts、context window、tools、execution state、human-in-the-loop、control flow、error compaction、小型專職 agents、trigger 與 stateless reducer 當成工程構件來管理。
2026年7月12日2 分鐘閱讀👁 5
AI Agents / Production Engineering / HumanLayer
HumanLayer 12-Factor Agents：把 LLM Agent 做成可上線軟體的 12 條工程原則
如果要把 agent 放到 production customer 手上，重點不是套框架，而是把 prompt、context、tool call、state、human approval、control flow 和 error handling 都工程化。
來源與查證
- Threads：wu.sirius 推薦想做 agents 的人必讀 HumanLayer 12-Factor Agents。
- GitHub：
humanlayer/12-factor-agents，描述為「Principles for building reliable LLM applications」。 - Repo metadata：逾 24K stars、內容授權標示為 Code Apache-2.0、Content CC BY-SA 4.0；GitHub API license 欄位顯示 NOASSERTION，因此商用引用需看 repo 內實際 license 檔與 badge。
12 條原則
| Factor | 名稱 | 重點 |
|---|---|---|
| 1 | Natural Language to Tool Calls | 把自然語言轉成明確工具呼叫，不要只靠自由文字。 |
| 2 | Own Your Prompts | prompt 是產品邏輯的一部分，要版本化、測試、可審查。 |
| 3 | Own Your Context Window | context window 是稀缺資源，要主動整理與注入。 |
| 4 | Tools Are Structured Outputs | 工具呼叫本質是結構化輸出，schema 要設計好。 |
| 5 | Unify Execution State | 執行狀態要可追蹤，不要散在 prompt、DB、logs。 |
| 6 | Launch / Pause / Resume | agent 任務要可啟動、暫停、恢復。 |
| 7 | Contact Humans With Tools | human-in-the-loop 也是一種工具，不是臨時人工干預。 |
| 8 | Own Your Control Flow | 不要把控制流全交給模型；關鍵流程應由程式掌控。 |
| 9 | Compact Errors | 錯誤要壓縮成可用訊息，避免把大量 noise 丟回模型。 |
| 10 | Small Focused Agents | 小而專職的 agents 比巨型萬能 agent 更穩。 |
| 11 | Trigger From Anywhere |