12-Factor Agents
本番向け LLM アプリケーションの設計原則 — humanlayer/12-factor-agents
12-Factor Agents は、Dex Horthy（HumanLayer）が公開しているガイドです。12 Factor Apps の精神を踏まえ、本番の顧客に届けられる LLM ソフトウェアを作るための原則を 12 項目に整理しています。
主張の中心は次のとおりです。多くの「AI エージェント」製品は、プロンプトとツールの袋をループするだけの薄いラッパーではなく、大部分は決定的なソフトウェアであり、LLM 呼び出しは必要な箇所にだけ差し込む、という設計が実際に強い、というものです。
ガイドは、ソフトウェアを有向グラフ（DAG）として捉える流れから始まります。従来のプログラムはフローチャートのように分岐と順序が決まっており、Airflow や Prefect などの DAG オーケストレータは観測性・リトライ・モジュール性を足してきました。
エージェントの約束は「DAG を捨て、目標と遷移だけ渡せば LLM が経路を選ぶ」ことでした。しかし実運用では、80% 品質で止まり、残り 20% でフレームワークを逆解析して作り直す、というパターンが繰り返される、と著者は述べています。
エージェントは次のループで動きます。
- LLM が次のステップ（構造化 JSON / ツール呼び出し）を決める
- 決定的なコードがツールを実行する
- 結果をコンテキストウィンドウに追記する
- 完了 intent になるまで繰り返す
initial_event = {"message": "..."}
context = [initial_event]
while True:
next_step = await llm.determine_next_step(context)
context.append(next_step)
if next_step.intent == "done":
return next_step.final_answer
result = await execute_step(next_step)
context.append(result)README の擬似コードに基づく。TypeScript 実装例は packages/create-12-factor-agent/template/ を参照。
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#e8eef8", "primaryTextColor": "#1a2540", "primaryBorderColor": "#4a6fa8", "lineColor": "#4a6fa8", "secondaryColor": "#f5f0e0", "tertiaryColor": "#faf8f5", "fontFamily": "JetBrains Mono, monospace", "fontSize": "14px"}}}%%
flowchart TD
A[初期イベント] --> B[コンテキスト構築]
B --> C{LLM: 次ステップ}
C -->|intent: done| D[最終応答を返す]
C -->|ツール呼び出し| E[決定的コードで実行]
E --> F[結果を context に append]
F --> B
著者が HumanLayer で見てきた典型的な旅路は次のとおりです。
- エージェントを作ると決める
- プロダクト設計・UX を固める
- フレームワークで素早く 70〜80% まで到達する
- 顧客向けには 80% では足りないと気づく
- プロンプト・フローを逆解析し、結局ゼロから作り直す
LLM がさらに賢くなっても、信頼性・スケール・保守性のためのコア技法は残る、という前提で 12 項目が書かれています。
| # | 原則 | 要点（要約） |
|---|---|---|
| — | Brief History of Software | DAG・オーケストレータからエージェントループへの文脈 |
| 1 | Natural Language to Tool Calls | 自然言語を構造化ツール呼び出しに変換し、決定的コードで実行する |
| 2 | Own your prompts | プロンプトをアプリのコードとして所有・版管理する |
| 3 | Own your context window | メッセージ形式に縛られず、最良の入力を設計する（コンテキストエンジニアリング） |
| 4 | Tools are structured outputs | ツールは構造化出力の一形態として扱う |
| 5 | Unify execution state | 実行状態とビジネス状態をコンテキスト上で統一する |
| 6 | Launch / Pause / Resume | 単純な API で起動・一時停止・再開できるようにする |
| 7 | Contact humans with tools | 人間への確認もツール呼び出しとしてモデル化する |
| 8 | Own your control flow | ループ・分岐・エラー処理を自前で持つ |
| 9 | Compact errors | エラーをコンテキストに収まる形で圧縮して渡す |
| 10 | Small, focused agents | スコープを小さく保ち、万能エージェントを避ける |
| 11 | Trigger from anywhere | CLI・Webhook・Cron など入口を増やし、ユーザーの居場所で動かす |
| 12 | Stateless reducer | エージェントを状態なしリデューサーとして設計する（fold 的な更新） |
| 13* | Pre-fetch context（付録） | 必要になりそうなコンテキストを先に取りに行く |
各原則には img/ 配下の図解（PNG/GIF）が対応しています。README の Visual Nav グリッドからも参照できます。
12-factor-agents/
├── README.md # ガイドの入口・12 原則リンク
├── content/ # 各 factor の Markdown 本文
│ ├── brief-history-of-software.md
│ ├── factor-01-…md … factor-12-…md
│ └── appendix-13-pre-fetch.md
├── img/ # 図解・アニメーション
├── packages/
│ ├── create-12-factor-agent/ # テンプレート生成（npx）
│ └── walkthroughgen/ # ワークショップ用ジェネレータ
├── workshops/ # 段階的ハンズオン（2025-05 など）
└── drafts/ # a2h 仕様など草案content/ がガイドの正本です。番号付き factor-0N-*.md が各原則の詳細で、重複していた旧ファイル名（factor-N- 単数形）はスタブ程度の行数のみ、とスキャン結果から判断できます。
create-12-factor-agent
packages/create-12-factor-agent は TypeScript 向けのスターターです。テンプレートには src/agent.ts、cli.ts、server.ts、state.ts などがあり、ワークショップの最終形に近い構成です。README では npx/uvx create-12-factor-agent の議論スレッドも案内されています。
workshops
workshops/2025-05/ などはセクションごとに段階を分けた教材です。CLI とエージェント、計算機ツール、BAML テスト、コンテキストウィンドウ、人間承認、HumanLayer Webhook まで、factor に沿って積み上げます。
walkthroughgen
packages/walkthroughgen は walkthrough YAML から教材コードを生成する CLI です。workshop ディレクトリの walkthrough.yaml と連携します。
- GitHub: humanlayer/12-factor-agents
- AI Engineer World's Fair トーク（YouTube）
- Anthropic — Building Effective Agents
- The Twelve-Factor App
- got-agents/agents — 同手法の OSS エージェント例
- HumanLayer Discord
本文・図のライセンス: コンテンツ CC BY-SA 4.0、コード Apache 2.0（README 記載）。