2011年、Herokuのエンジニアたちは「12-Factor App」と呼ばれるドキュメントを公開しました。これはコードでもフレームワークでもなく、スケーラブルで保守性の高いSaaSアプリケーションを構築するための方法論です。
このドキュメントは後に、クラウドネイティブ時代におけるデファクトスタンダードとなりました。Docker、Kubernetes、各種マイクロサービスフレームワークの根底には、いずれも12-FactorのDNAが息づいています。
現在、AIエージェントに対しても同じことを試みる動きがあります。
humanlayer/12-factor-agents は21,600スター、273回のコミットを記録しています。著者のDexは率直にこう述べています：
私はCrewAIやLangChainのような「すぐに使える」ものから、「ミニマル」を謳うSmolAgents、さらには「プロダクションレディ」を標榜するLangGraphやGriptapeまで、あらゆるエージェントフレームワークを試してきました。しかし、自称「AIエージェント」の製品の多くは、実際にはそれほどagentic（自律的）ではありません。それらのほとんどは決定論的なコードであり、適切な箇所にLLMを少し散りばめただけに過ぎないのです。
耳に痛い言葉に聞こえるかもしれませんが、よく考えてみれば確かにその通りです。
核心的な見解：優れたエージェントは「目標を与えて勝手に走らせる」ものではない
12-Factor Agentsの第1原則は、多くの人が持つエージェントに対する認識を覆すものです：
Factor 1: Natural Language to Tool Calls
LLMの核心能力は「思考」することではなく、自然言語を構造化されたツール呼び出しに変換することにあります。これは、エージェント設計の重心を「LLMに際限のない自由の中で試行錯誤させる」ことではなく、「適切なツールを提供する」ことと「正しい呼び出し形式を定義する」ことに置くべきであることを意味します。
Factor 8: Own your control flow（制御フローを自ら掌握する）
この原則はさらに重要です。多くの人がエージェントを書く際のパターンは「プロンプトを与え、ツールを山ほど用意し、完了するまでループさせる」というものです。12-Factorは明確に指摘しています：それは通用しないと。
本番環境で実際に運用できるエージェントでは、制御フローは必ず開発者が定義しなければなりません。どのステップが確定的か、どのステップをLLMの判断に委ねるか、いつ人間の介入が必要か、エラー発生時にどうフォールバックするか。LLMはエンジンですが、ハンドルは必ずあなたの手元になければなりません。
12の原則をざっと確認する
これら12の原則は、エージェント開発のあらゆる側面を網羅しています：
- Factor 1-4 は「ツール呼び出し」の基盤ロジックについて：自然言語→構造化出力→コンテキスト管理→ツール定義
- Factor 5-7 は「実行状態」について：ビジネス状態と実行状態の統合管理方法、一時停止/再開方法、人間の介入の導入方法
- Factor 8-10 は「アーキテクチャ設計」について：制御フローの帰属、エラーの圧縮、エージェントの粒度
- Factor 11-12 は「統合とデプロイ」について：あらゆる場所からのトリガー、エージェントをステートレスなreducerへ変換
その中でも特に実用的なものをいくつかピックアップして解説します。
Factor 3: Own your context window（コンテキストウィンドウを自ら掌握する）
コンテキストウィンドウは無制限ではありません。12-Factorは、コンテキストを戦略的に管理する必要があると強調しています。どの情報を保持し、どの情報を圧縮し、どの情報を破棄するか。そうしなければ、対話が長くなるにつれてLLMのパフォーマンスは急激に低下します。
Factor 7: Contact humans with tool calls（ツール呼び出しで人間に連絡する）
この原則は非常に現実的です。エージェントが不確実な状況に遭遇した場合、「闇雲に推測する」のではなく、ツール呼び出しを通じて人間の介入をリクエストするべきです。一見単純に聞こえますが、大多数のエージェントフレームワークはこれをファーストクラス（第一級の要素）として設計していません。
Factor 12: Make your agent a stateless reducer（エージェントをステートレスなreducerにする）
これは最も「エンジニア的思考」に満ちた原則かもしれません。エージェントをreducer関数として想像してください。イベントと現在の状態を与えると、新しい状態を返します。ステートレスであるということは、水平スケーリングが可能になり、リトライが可能になり、モニタリングも容易になることを意味します。
なぜこのガイドに注目すべきなのか？
現在のAIエージェント開発における最大の問題は「技術が十分に強力ではない」ことではなく、**「方法論がまだ確立されていない」**ことだからです。
誰もが試行錯誤し、落とし穴にハマり、車輪の再発明を繰り返しています。12-Factor Agentsの価値は、これらの散在する経験を体系化し、議論可能で、反復可能で、継承可能な原則のセットに変えようとしている点にあります。
これは特定のフレームワークに縛られず、特定の技術スタックを推奨するものでもありません。これが答えようとしているのは、より根本的な問いです：LLMを使って実際に使えるプロダクトを構築したい場合、どのような原則に従うべきか？