LangChain や CrewAI でデモは作れたものの、本番品質に引き上げようとした途端、フレームワーク内部のプロンプトや制御フローを書き換える羽目になった経験を持つエンジニアは少なくないはずです。
「もう一度作り直すべきか」「フレームワークの中で粘るべきか」と迷っているときに目に入るのが、GitHub で 21,672 スターを集める humanlayer/12-factor-agents です。LLM 時代の「The Twelve-Factor App」を目指して整理されたこの設計原則集は、フレームワークそのものではなく、本番品質のエージェントを構築するための判断軸を提供しています。
ただ、12 個の原則を順に読み下すだけでは「自社の文脈で採用すべきか」「いつから取り入れるべきか」が判断しづらいのも事実です。本記事では、12-factor-agents の位置付け、CrewAI / Letta / AutoGen との立ち位置の違い、12 個の原則の要点、自社プロダクトへの適用判断軸を解説します。
12-factor-agentsとは何か
12-factor-agents は、HumanLayer の創業者 Dex Horthy 氏が中心となって整理した、本番運用に耐える LLM エージェントの設計原則集です。リポジトリは humanlayer/12-factor-agents で公開されており、2025年9月21日時点で 21,672 スター・1,627 フォークを集めています。主要言語は TypeScript ですが、原則自体は言語非依存です。
名前から推察できる通り、Heroku が提唱した The Twelve-Factor App の系譜を明示的にオマージュしています。クラウドネイティブ時代の設計原則が「12 ファクター」として広く共有されたように、LLM エージェント時代にも共通の設計原則を持とうという試みです。
ここで強調しておきたいのは、12-factor-agents はフレームワークではなく設計原則集であるという点です。pip install や npm install で導入する実行可能なライブラリではなく、既存コードベースに段階的に適用できるパターン集として整理されています。「フレームワークを採用するかどうか」とは別軸の選択肢として扱う必要があります。
著者の Dex Horthy 氏は、100 社以上の SaaS 事業者へのヒアリングと、主要なエージェントフレームワークを触った経験を基にこの原則集を整理したと説明しています。中心となる主張は「成功している本番 AI アプリケーションは『LLM＋ツール』のような構造ではなく、ほぼ決定論的なソフトウェアの中に戦略的に LLM を埋め込んだもの」というものです。
本番運用のLLMエージェントが直面する壁
12-factor-agents が解決しようとしている課題は、LLM エージェントを本番投入する際にぶつかる「70〜80% の壁」です。
フレームワークを使えば社内デモや PoC は数日で立ち上がります。ところがプロダクトとしてユーザーに提供しようとすると、品質が 70〜80% から先になかなか進みません。エッジケースで意図しない挙動が出る、ハルシネーションが混入する、ツール呼び出しが冗長になる。こうした問題を潰そうとすると、結局はプロンプトの中身・コンテキストウィンドウの構成・制御フローの細部に手を入れる必要が出てきます。
しかしフレームワークは、まさにそれらを「便利な抽象化」として隠蔽していることが多いものです。改善のためにフレームワーク内部に踏み込み、独自フォークを抱え込み、最終的には「フレームワークを使わずに書き直した方が早かった」と結論するチームが少なくありません。HumanLayer 公式の 12-Factor Agents でも、「80% を超える品質に到達するには、フレームワーク・プロンプト・フローをリバースエンジニアリングする必要がある」と指摘されています。
12-factor-agents は、この問題に対し、最初からプロンプト・コンテキスト・制御フローを自分の手で握ることを推奨します。
12-factor-agentsが提示する12の設計原則
リポジトリで提示されている 12 個のファクターを整理します。一次情報は公式 README (humanlayer/12-factor-agents) を参照してください。12 個を全部一度に取り入れる必要はなく、著者自身もコアとなる 4 つのファクター（Factor 2 / 3 / 5 / 8）から優先的に取り組むことを推奨しています。
コアとなる4つのファクター
# | ファクター名（原文） | 要点 |
|---|---|---|
2 | Own Your Prompts | プロンプトを型付き・Git 管理・差分レビュー・テスト可能な形で書く |
3 | Own Your Context Window | XML / YAML 等のカスタムシリアライズで、トークン効率とモデルの注意配分を最適化する。著者が「最も重要」と位置付ける |
5 | Unify Execution State and Business State | 実行履歴とビジネスデータを単一の |
8 | Own Your Control Flow |
|
この 4 つに共通するのは「フレームワーク任せにせず、自分で握る」という姿勢です。プロンプトの文面、LLM に渡す前のコンテキストの構造、状態管理、ループの制御。これらを抽象化の向こう側に置いてしまうと、品質改善のための観察可能性が失われます。特に Factor 3 は、コンテキストウィンドウに何をどの順序で詰め込むかがエージェントの精度を左右する最大の変数だという主張です。
その他の8つのファクター
# | ファクター名（原文） | 要点 |
|---|---|---|
1 | Natural Language to Tool Calls | LLM の役割は「非構造的な意図」→「構造化された |
4 | Tools are Structured Outputs | ツールは LLM の戻り値型として定義するデータ構造である |
6 | Launch/Pause/Resume with Simple APIs |
|
7 | Contact Humans with Tool Calls | 人間を「高レイテンシのツール」として扱い、承認要求も構造化ツール出力として表現する |
9 | Compact Errors into Context Window | ツール失敗を要約して |
10 | Small, Focused Agents | 巨大エージェントではなく、3〜20 ステップで完結する「マイクロエージェント」を連結する |
11 | Trigger from Anywhere | Slack / API / Cron など多様な入口に対し、同じステートレスロジックを実行できるよう設計する |
12 | Make Your Agent a Stateless Reducer | エージェントは |
12 個全体を貫いているのは「LLM は強力だが、その周囲を決定論的なソフトウェアで固めるべきだ」という思想です。エージェントを「状態を持つ複雑な存在」ではなく、イベントログを入力として次のアクションを返す純関数（Factor 12）として扱うことで、テスト・リプレイ・観察可能性が一気に楽になります。
フレームワーク（CrewAI / Letta / AutoGen）との立ち位置の違い
12-factor-agents はフレームワークの代替ではなく「フレームワークを使わない選択肢」を提示する原則集です。代表的なフレームワークと並べると、立ち位置の違いが明確になります。
リポジトリ | 提供形態 | 12-factor-agents との関係 |
|---|---|---|
実装フレームワーク（Crews + Flows） | 役割を持つエージェントを協調させる高レベル API を提供。12-factor-agents は逆に「抽象化を捨てて決定論的なコードを自分で書く」立場 | |
ステートフルエージェントプラットフォーム | 長期メモリ・自己改善をプラットフォーム内部に閉じ込める。12-factor-agents は Factor 5 / 12 でステート管理を呼び出し側に開く方針 | |
マルチエージェント協調フレームワーク（メンテナンスモード） | イベント駆動マルチエージェント協調を抽象化。12-factor-agents は薄い抽象化＋マイクロエージェント連結（Factor 10）を推奨 |
CrewAI や AutoGen は「複数のエージェントを役割分担させて協調させる」高レベル抽象化をフレームワーク側で提供します。Letta はメモリ・自己改善・長期実行をプラットフォーム内部で巻き取ります。いずれも「フレームワークが面倒を見てくれる範囲」を広く設計しているのが特徴です。
「CrewAI と 12-factor-agents、どちらを選ぶか」は同じ階層での比較ではなく、「フレームワークによる開発速度を重視するか／自前実装による制御性を重視するか」という別軸の選択になります。
自社プロダクトに12-factor-agentsを取り入れる判断軸
採用を強く検討すべきケース
- 本番ユーザーに提供する AI 機能を担当している: 外部顧客向けの品質が求められる場合、フレームワークの抽象化が逆に足かせになる場面に遭遇します
- 既存フレームワークで品質が頭打ちになっている: フレームワーク内部を読み込む時間が増えてきたら、原則集をベースにした自前実装への移行を検討する価値があります
- 観察可能性が品質改善のボトルネックになっている: 状態遷移・ツール呼び出しを Thread イベントログとして統一管理する構成（Factor 5）が効果を発揮します
急いで採用しなくてよいケース
- PoC や社内ツールなど 70〜80% 品質で十分な用途: CrewAI や LangChain で素早く立ち上げる方が合理的です
- エージェントが単純なツール呼び出し 1〜2 回で完結する: 制御フローを自前で書くメリットが薄く、フレームワークの恩恵が大きくなります
取り入れ方の優先順位
著者は「全部一度に取り入れる必要はない」と明示しています。実務的には次の順序が現実的です。
- まず Factor 2 / 3 を握る: プロンプトとコンテキストの組み立てを Git 管理下のコードに引き上げる
- 次に Factor 5 / 8 を整える: 実行状態とビジネス状態を統一した Thread イベントログにし、制御フローを
whileループとして明示的に書く - その後 Factor 10 / 12 を適用する: 巨大エージェントを分解し、ステートレスなリデューサとして再設計する
- 最後に Factor 7 / 11 で周辺を整える: 人間承認フローや多入口対応を構造化ツールとして組み込む
この優先順位は HumanLayer 公式の 12-Factor Agents や README の構造とも整合的です。
採用にあたっての注意点
ライセンス: README には「コードは Apache 2.0、コンテンツ・画像は CC BY-SA 4.0」と明記されていますが、本リポジトリのライセンスは GitHub が標準 SPDX として識別できない形式（NOASSERTION）です。ご利用前に公式リポジトリの LICENSE ファイルをご確認ください。社内資料に転載する場合は CC BY-SA 4.0 の継承条件、コード断片を製品に組み込む場合は Apache 2.0 の表示要件をそれぞれ確認することをおすすめします。
言語非依存だが TypeScript 例が中心: 主要言語は TypeScript（80.2%）で、Python と Jupyter Notebook が合計約 11.2% を占めます。サンプルコードは TypeScript が中心ですが、12 個のファクター自体は言語非依存のため、Python スタックでも原則の解釈には支障ありません。
更新ペースと議論の場: 最終更新は 2025年9月21日（pushed_at: 2025-09-21）です。フレームワークと違い「バージョンアップで API が変わる」種類のものではないため、メジャーアップデートを気にする必要はありません。コミュニティでの解釈や追加ファクターの議論は周辺リポジトリで進行しているため、最新動向を追う場合は GitHub Issues / Discussions と HumanLayer 公式サイトを定期的に確認するとよいでしょう。
まとめ
12-factor-agents は、フレームワークを採用するかしないかという比較ではなく、本番品質の LLM エージェントを構築するための設計原則集として位置付けるのが正解です。21,672 スターという指名検索需要の強さは、多くのエンジニアが「フレームワーク内部に深入りする前の段階で、判断材料を持っておきたい」と感じている裏返しでもあります。
次の一歩としては、公式 README (humanlayer/12-factor-agents) を一読し、コアファクター 4 つ（Factor 2 / 3 / 5 / 8）を自社実装のどこにマッピングできるか書き出してみるのがおすすめです。全部を一度に取り入れる必要はありません。プロンプトとコンテキストを握り直すだけでも、本番品質に近づくための観察可能性は大きく改善するはずです。
