AIエージェントを作り始めると、最初の70〜80%は意外とすんなり進む。問題はその先だ。
フレームワークを使って素早くプロトタイプを動かし、動作確認を終えた後、品質を本番レベルまで引き上げようとした瞬間に行き詰まる——そんな経験をしたエンジニアに向けて公開されたのが「12-Factor Agents」だ。2026年5月時点でGitHubのスターは約1.97万件を記録している。
この記事でわかること
- なぜ「プロンプト+ツール+ループ」では本番品質に届かないのか
- 12-Factor Agentsが定義する12の原則の概要
- 特に重要なコンテキスト管理・エラー処理・エージェント規模の考え方
12-Factor Agentsとは
HumanLayerを開発したDex Horthy氏が、100社以上のSaaSビルダーへのヒアリングをもとに作成したOSSガイドだ。Herokuが提唱したWebアプリ開発のベストプラクティス「12 Factor Apps」にならい、信頼性・拡張性・保守性を持つLLMエージェントを作るための12の原則をまとめている。TypeScriptのコード例が中心だが、Pythonを含む任意の言語で適用できる。
「プロンプト+ツール+ループ」の限界
一般的なLLMエージェントはこのループで動く。LLMが次のアクションをJSON形式（ツール呼び出し）として出力し、決定論的なコードがそのツールを実行し、結果をコンテキストウィンドウに追記する。これを「完了」と判断されるまで繰り返す。
最初のうちはこのパターンで十分に機能する。多くのビルダーが辿る道筋はこうだ。フレームワークを手に取って素早く構築する。品質が70〜80%まで到達する。しかしそれ以上に向上させようとすると、フレームワーク内部のプロンプトや制御フローを掘り起こさなければならなくなる。最終的に最初から書き直すことになる。
Horthy氏はこの問題の根本を指摘する。「本番品質の優れたエージェントは、実際にはほとんどが決定論的なコードであり、LLMのステップをちょうどよいポイントに散りばめたものだ」。フレームワークに制御を任せきりにすることが、この認識を遅らせる原因になっている。
12の原則
1. 自然言語をツール呼び出しに変換する
LLMの最大の強みは、曖昧な自然言語の指示をAPIが受け取れる構造化データへと翻訳できることだ。エージェントの入力インターフェースを自然言語として設計することで、ユーザーはシステムの内部仕様を知らなくても操作できるようになる。
2. プロンプトを自分で管理する
フレームワークが自動生成するプロンプトに依存しないこと。プロンプトはアプリケーションのロジックとLLMをつなぐ主インターフェースだ。完全に自分でコントロールできれば、モデルの差し替えや挙動の調整を自由に行える。
3. コンテキストウィンドウを自分で管理する
「コンテキストエンジニアリング」とも呼ばれ、このガイドの中でも特に注目されている原則だ。LLMはステートレスな関数であり、入力の質が出力の質を決める。
コンテキストには、プロンプト・外部データ（RAG）・過去のツール呼び出し結果・会話履歴・出力フォーマットの指示が含まれる。フレームワークが提供するデフォルトのrole: user/assistant/tool形式は汎用的だが、ユースケースに合わせた独自フォーマットに最適化することで、トークン効率と精度を同時に向上できる。
4. ツールは構造化出力である
ツール呼び出しを特別な仕組みとして捉えるのではなく、LLMによる構造化出力の一種として捉える。この視点を持つことで、ツールの定義方法やエラーハンドリングの設計を柔軟にコントロールできるようになる。
5. 実行状態とビジネス状態を統合する
エージェントの実行状態（どのステップまで進んだか）とビジネス状態（注文IDやユーザーIDなど）を別々のストアで管理しない。同一のデータストアで扱うことで、再開・ロールバック・監査がシンプルになる。
6. シンプルなAPIで起動・一時停止・再開を実現する
エージェントは実行中に一時停止し、外部からの承認や追加情報を待った後に再開できなければならない。これをシンプルなAPIとして設計しておくことで、人間との協調ワークフローを自然に組み込める。
7. ツール呼び出しで人間に連絡する
人間への確認や通知を「特別な処理」として実装しない。ツール呼び出しの一種として設計することで、エージェントは同じ制御フローの中で人間への問い合わせを行える。チャットUIに依存しない柔軟な承認フローを実現できる点が特徴だ。
8. 制御フローを自分で管理する
フレームワークの制御フローに乗っかるのではなく、エージェントのループをコードとして明示的に書く。制御フローを手放すことは、予測不能な挙動を受け入れることと同義だ。
9. エラーをコンテキストウィンドウにコンパクトにまとめる
エラーが発生したとき、スタックトレース全体をコンテキストに詰め込まない。LLMが理解できる簡潔な形式でエラーを渡すことで、エージェントが次のツール呼び出しで問題を修正する自己修復の仕組みが機能する。エラーの整形はエージェントの回復力を直接左右する。
10. 小さく、集中したエージェントを作る
1つのエージェントに多くのことをやらせない。タスクの複雑度が上がるほどコンテキストは長くなり、LLMはフォーカスを失いやすくなる。3〜10ステップ、最大でも20ステップ程度に収まるようスコープを絞ることを推奨している。
LLMが将来さらに高性能になっても、この原則は有効だ。コンテキストウィンドウの信頼性が上がれば、エージェントの範囲を少しずつ広げればよい。今日できる範囲で確実に品質を出すことが、長期的な拡張性の土台になる。
11. どこからでもトリガーでき、ユーザーのいる場所で動く
エージェントの起動条件を特定のUIやチャンネルに縛らない。ユーザーメッセージ・cronジョブ・Webhookのいずれからでも同じエージェントを呼び出せる設計にする。
12. エージェントをステートレスなレデューサーにする
エージェント自体は状態を持たず、外部の状態ストアから読み込んで処理し、結果を返す純粋な関数として設計する。水平スケール・テスト・デバッグのいずれも容易になる。
このガイドが向いている人
AIエージェントを既存のプロダクトに組み込もうとしている開発者、または「フレームワークで作ったが80%から先が進まない」と感じているエンジニアに特に役立つ内容だ。LangChain・LangGraph・smolagentsのような既存フレームワークを否定するものではなく、どのフレームワークを使っていても適用できる原則として設計されている。
コントリビューションも受け付けており、フォーク数は1,500件を超えている。実装サンプルや各原則の詳細ページもGitHubで公開されている。
本番エージェントに必要なのは原則の理解
デモで動くエージェントと、本番で動くエージェントの差は、使うフレームワークではなく設計の判断にある。12-Factor Agentsが整理した12の原則は、エージェント開発で繰り返し直面する問題への具体的な処方箋だ。コンテキストを誰が管理するか、制御フローをどこに持つか、エラーをどう渡すか——これらの判断を意識的に行えるかどうかが、品質の分岐点になる。