12ファクターエージェント: 信頼できるLLMアプリケーションのパターン
(github.com/humanlayer)- 12-Factor Agentsは、本番環境の顧客に提供できるほど信頼性の高いLLMベースのソフトウェアを作るための12の原則を整理した公開ガイド
- 良いエージェントは、「プロンプトとツールの束を与えて目標達成まで反復する」形よりも、主に決定論的ソフトウェアの必要な地点ごとにLLMステップを挿入する構造に近いとする
- 一般的なエージェントループは、LLMが次のステップを構造化JSONツール呼び出しとして決定し、決定論的コードがそれを実行した後、結果をコンテキストウィンドウに追加し、完了まで繰り返す
- 多くのSaaSビルダーはフレームワークで素早く始めて70〜80%の品質に到達するが、顧客向け機能には不十分で、フレームワーク・プロンプト・フローをリバースエンジニアリングするか、最初からやり直す流れを経験すると述べる
- 顧客に高品質なAIソフトウェアを最速で提供する方法は、エージェントフレームワーク全体を導入することではなく、小さくモジュール化されたエージェント構築の概念を既存製品に統合するやり方
プロジェクトの問題意識
- 12-Factor Agentsは、12 Factor Appsの精神をLLMアプリケーション構築の原則に適用しようとする公開プロジェクト
- 核心となる問いは「本番環境の顧客に任せられるほど実際に優れたLLMベースのソフトウェアを作るために、どんな原則を使えるのか」
- さまざまなエージェントフレームワークを試し、YC内外の技術系起業家たちと対話した経験から出発している
- 多くの起業家は、本番の顧客向けエージェントではフレームワークを多用するより、自前のスタックを構築している
- 「AI Agent」と呼ばれる多くの製品は、完全にエージェント的というより、主に決定論的コードにLLMステップを適切に混ぜた形だと見る
エージェントに対する基本的な見方
- 良いエージェントは、「プロンプト、ツール群、目標達成まで反復」というパターンだけでは構成されない
- ソフトウェアは有向グラフ（DG）として見ることができ、過去にプログラムをフローチャートで表現していた理由もここにある
- およそ20年前からDAGオーケストレーターが広く使われ始めた
- エージェントの約束は、エンジニアがすべてのステップと例外をコーディングする代わりに、目標と遷移だけを与え、LLMにリアルタイムで経路を決めさせること
- この方式には、より少ないコードで済み、エラーから回復し、LLMが新しい解決策を見つけられるという期待がある
- しかし実際には、このアプローチは期待したほどうまく機能しないとする
エージェントループの実行モデル
- 基本的なエージェントループは、LLMの判断 → ツール実行 → 結果をコンテキストに追加 → 反復で構成される
- フローは次のとおり
- 初期コンテキストは、ユーザーメッセージ、cron実行、webhookのような開始イベント
- LLMが次のステップまたは完了可否を判断する
- 次のステップは構造化JSON形式のツール呼び出しとして出力される
- 決定論的コードがツール呼び出しを実行する
- 実行結果がコンテキストウィンドウに追加される
- 次のステップが
doneなら最終回答を返す
- READMEの例では、
llm.determine_next_step(context)で次のステップを決め、execute_step(next_step)で実行した後、結果をコンテキストに付加するループを示している
なぜ12の原則が必要なのか
- HumanLayerを作る中で少なくとも100人のSaaSビルダーと話し、彼らは概して既存製品をよりエージェント的にしようとしている技術系起業家だった
- 一般的な道筋は次のとおり
- エージェントを作ると決める
- 製品設計とUXマッピング、解決すべき問題を定める
- 素早く進めるため特定のフレームワークを選ぶ
- 70〜80%の品質レベルに到達する
- 80%の品質では大半の顧客向け機能に十分でないと気づく
- 80%を超えるにはフレームワーク、プロンプト、フローなどをリバースエンジニアリングしなければならない
- 結局、最初から作り直す
- この批判はフレームワークやその制作者を攻撃する意図ではなく、フレームワークはAIエコシステムを加速させたと述べている
- MCPは扱わず、例は主にTypeScriptを使っているが、Pythonや他の言語にも適用できるとしている
12のファクター
- LLMが今後さらに強力になっても、LLMベースのソフトウェアをより信頼可能で、拡張しやすく、保守しやすくする中核的なエンジニアリング手法は残るとする
- 12のファクターは次のとおり
- Factor 1: Natural Language to Tool Calls: 自然言語をツール呼び出しに変換
- Factor 2: Own your prompts: プロンプトを自分で管理する
- Factor 3: Own your context window: コンテキストウィンドウを自分で管理する
- Factor 4: Tools are just structured outputs: ツールは単なる構造化出力
- Factor 5: Unify execution state and business state: 実行状態とビジネス状態を統合する
- Factor 6: Launch/Pause/Resume with simple APIs: シンプルなAPIで開始・一時停止・再開する
- Factor 7: Contact humans with tool calls: ツール呼び出しで人に連絡する
- Factor 8: Own your control flow: 制御フローを自分で管理する
- Factor 9: Compact Errors into Context Window: エラーをコンテキストウィンドウに圧縮して入れる
- Factor 10: Small, Focused Agents: 小さく焦点の定まったエージェント
- Factor 11: Trigger from anywhere, meet users where they are: どこからでもトリガーし、ユーザーがいる場所で応答する
- Factor 12: Make your agent a stateless reducer: エージェントをステートレスなリデューサーにする
- 追加の助言としてFactor 13: Pre-fetch all the context you might needも含まれる
適用方法と関連資料
- フレームワーク全体を導入して、事実上グリーンフィールドでの書き直しに進むやり方は逆効果になりうるとする
- エージェントを良くする中核原則の大半はフレームワーク導入でも得られるかもしれないが、顧客に高品質なAIソフトウェアを素早く届ける道は、より小さくモジュール化された概念を既存製品に統合することだと述べる
- このモジュール型の概念は、AIの背景がない熟練ソフトウェアエンジニアでも定義して適用できるとしている
- 関連資料としてAnthropicのBuilding Effective Agents、Prompts are Functions、Library patterns: Why frameworks are evil、The Wrong Abstractionなどが挙げられている
- コンテンツと画像はCC BY-SA 4.0、コードはApache 2.0ライセンスで提供される
1件のコメント
Hacker News の意見
この記事のポイントは素晴らしい。数年間自分で試してまとめた学びのリストもある: https://mg.dev/lessons-learned-building-ai-agents/
今なら最も大きく追加したい項目は、最も低いレベルの計画ループを自分で所有せよ、ということ。動的な計画はよいが、観察・判断・決定・行動（OODA）ループを自分で持ち、答えに収束しているかを判定するヒューリスティック（例: スコア化）や、抜け出す条件（例: 最大反復回数）を置くべき
さらに、ワークフローエンジンを入れることも検討に値する。モデルに複数ターンにわたって暗黙のワークフローを維持・進行させるより、モデルにそのエンジンで実行されるワークフロー仕様を作らせ、各ステップで必要なら再びモデルを呼び出す方式のほうがよい
DSPY のようなライブラリが factor-2 にどう当てはまるのか気になる: https://dspy.ai/, https://github.com/humanlayer/12-factor-agents/blob/main/con...
読んでいると、BAML でプロンプトを生成するという内容があった。個人的には、非構造化データから構造化情報を抽出するためのプロンプトを手で書くのは簡単ではなく、DSPY ではこれまでかなり良い経験をしている
BAML の生プロンプトを使うなら、DSPY の生プロンプトを使う方式をどう見ているのか気になる: https://dspy.ai/tutorials/observability/#using-inspect_histo...
https://www.chrismdp.com/beyond-prompting/ この記事に完全に同意するわけではないが、パンチカード → アセンブリ → C → 高水準言語という比較はここではかなり有用
まだ適切な抽象化がいつ出てくるのか分からないし、LangChain や DSPY が AI の「C プログラミング言語」だとはまだ思わない。いつかそうなる可能性はある
今はトークンを検査し、system/user/JSON のような特殊トークンの順序を変え、ライブラリのサポートを待って縛られることなく、新しいモデルの特異点に合わせて素早く調整できる低レベルの作業台を使う
フレームワークパターンに関する古い、あまり知られていない記事がキャリアを通じてずっと腑に落ちており、ここにも当てはまると思う: https://tomasp.net/blog/2015/library-frameworks/
LLM は記事で説明されている理由、そしてそれ以上の理由から、特に今のようにすべてが急速に変化している時期には、フレームワークよりライブラリのように使うほうがよい。ただし、フレームワークのほうがより魅力的で売りやすく、ロックインや付加サービスにつながるため、より多く宣伝される
独自の「AI エージェントフレームワーク」である SecAI を、アクターモデル、状態機械、アスペクト指向プログラミングを基盤に作り、公開したところ: https://github.com/pancsta/secai
特に 5 番「実行状態とビジネス状態を統合せよ」と 8 番「制御フローを自分で所有せよ」が気に入っている。SecAI の中核はグラフ制御フローライブラリであり、DAG ではなくマルチグラフを使い、LLM 呼び出しはグラフノードに埋め込まれる
フローはネゴシエーション、キャンセル、状態を持つ関係によって強化され、より有機的に動作する。他のフレームワークでよく欠けている専用開発ツール（dbg、repl、svg）、失敗を前提にしたプログラミング、すべてのステップを詳細に検査する機能、自動データエクスポート（メトリクス・トレース・ログ・SQL）、シンプルな統合（bash）も含む
最初の技術デモも公開しており、AtomicAgents から移植した deepresearch のリファレンス実装で開発ツールを見せている: https://youtu.be/0VJzO1S-gV0
Send/Stop ボタンは実質的に「Factor 6. シンプルな API で開始/一時停止/再開」であり、ネットワーク透過性もあるため拡張可能
もう 1 つ追加するなら、規模が大きくなったときのコストを計画すべき
こうしたシステムは規模が大きくなると安くないので、ある作業が決定的なコンポーネントで処理可能なら、まずそちらを試すのがよい。幻覚とレイテンシを減らすだけでなく、最終的な利益にも大きな差を生み得る
各原則を追いやすくするには、複数の factor を貫く一貫した物語があるとよい。実際に近いシステム例を使い続ける形なら、理解しやすくなりそう
コミュニティとともに公開の場で継続的に発展させていきたい
素晴らしい。すでに80%は苦労して学んだし、残りの20%も読む価値がありそう。
個人的には LangGraph + pydantic スキーマ の組み合わせでうまくいった。他の人が有用に使っているツールも気になる。
今まさに必要としていたタイミングで出てきた記事。
オーディオビジュアル・サンドボックスのアイデアを実験中。vvvv のようなものだが、ずっと単純で最小限の機能だけを備えた形: https://kfs.mkj.lt/#audiovisllm, https://vvvv.org/
特定のタスクを担当し、出力が非常に制限された LM、または簡単なローカルニューラルネットワークの「ノード」を挿入する、というのがアイデア。なので「question -> answer: float」のような例がとても魅力的。自分の場合、質問の一部はかなり抽象的になり得るが、多段パイプラインも興味深い。
詳しく読んではいないが、できるだけ 決定的なコード を多く書き、LLM はできる限り少なく使いたい。
そのほうが、予測可能な結果、低い運用コスト、そして他人が同じアプリをすぐに複製しにくいというシグナルになると思う。LLM を他のシステムにつなげるためにバズワード的な接着剤をそのまま使うより、自分でツールを作るほうを選ぶ。
こうした条件が満たされない、あるいは必要でないなら、誰かが同じ解決策をあっという間にバイブコーディングで作れてしまうと思う。制御を維持すべきだ。制御という丘で死ぬ覚悟だ。だからといって LLM に感嘆していないという意味ではなく、むしろ正反対。