12因子エージェント：信頼性の高いプロダクショングレードLLMアプリケーション構築のための設計原則

はじめに

“12ファクター・エージェント" 特定のソフトウェア・ライブラリやフレームワークではなく、信頼性が高く、スケーラブルで保守が容易なLLM（大規模言語モデル）アプリケーションを構築するための設計原則のセットです。このプロジェクトは開発者のDexによって始められた。彼は、多くのチームが既存のAI Intelligent Bodyフレームワークを使って顧客向けの機能を開発する際に、70-80%レベルの品質を簡単に達成できるが、本番環境でこのボトルネックを突破するのは例外的に困難であることを発見した。根本的な原因は、多くの高度なフレームワークが基本的な制御を隠しすぎているため、深いカスタマイズや最適化が必要な場合、開発者はリバースエンジニアリングやゼロからのやり直しを余儀なくされることだ。そこでこのプロジェクトでは、古典的なソフトウェア開発方法論「12ファクター・アプリ」のアイデアを借り、12の基本原則を提案する。これは、ソフトウェア・エンジニアに、既存の製品を破壊的に書き換えるのではなく、モジュール化されたAI機能を既存の製品に段階的かつ確実に統合するための思考ガイドを提供することを目的としている。その核となる考え方は、優れたAIアプリケーションは本質的に優れたソフトウェアであり、その主要部分は決定論的コードで構成されるべきであり、LLMの魔法は最も必要とされる部分に正確に適用されるべきであるというものである。

コース一覧

• 序文ソフトウェアの歴史
• 原則 I：自然言語からツール呼び出しユーザーの自然言語入力を1つ以上の特定のツール（関数）呼び出しに安定的にマッピング。
• 原則 II：キュー・ワードをコントロールするプロンプトは動的に生成されるのではなく、アプリケーションのコアコードの一部であるかのようにバージョン管理され、管理されます。
• 原則 III：コンテキストウィンドウをコントロールする信頼性を達成する鍵は、LLMへの入力の文脈的内容を正確に制御することである。
• 原則 IV：構造化されたアウトプットとしてのツールツールとは、LLMに単なる関数の集まりではなく、構造化されたアウトプットを出させる方法だと考えてください。
• 原則V：実施状況とビジネス状況の調和インテリジェンスの運用状態をアプリケーションのコアビジネス状態モデルと組み合わせ、状態の一貫性を実現する。
• 原則 VI：シンプルなAPIによる起動/一時停止/再開インテリジェンスの長時間タスクを、シンプルなインターフェイスを通じて外部システムから制御できるようにする。
• 原則VII：ツールの呼び出しを通じて人間と対話するインテリジェントが人間の入力やレビューを必要とする場合は、特別な処理ではなく、標準的なツール呼び出しによってトリガーされるべきである。
• 原則8コントロール・フローをコントロールするアプリケーションの中核となるビジネスロジックとプロセス変換は、決定論的なコードによって導かれるべきであり、LLMの裁量に完全に委ねられるべきではない。
• 原則IXエラーメッセージをコンテキストウィンドウに圧縮ツールの実行に失敗した場合、そのエラーメッセージは要約され、修正のためにLLMにフィードバックされる。
• 原則X：小さく集中したインテリジェンスの構築何でもできる1つの巨大なインテリジェンスを構築するよりも、小さくてコンパクトな複数のインテリジェンスを組み合わせる傾向にある。
• 原則XIどこでもトリガー、どこでも対話Intelligentsiaは、さまざまなイベントソース（APIリクエスト、データベースの変更、定時タスクなど）からトリガーされ、ユーザーがいるプラットフォーム（Slack、電子メールなど）で対話できる必要があります。
• 原則XIIステートレス・リデューサーとしてのインテリジェンスの設計Reduxのアイデアを取り入れ、スマート・ボディは、現在の状態とイベントを受け取り、新しい状態を返す純粋な関数として設計されている。

ヘルプの使用

「12ファクター・エージェント」は、インストール・プロセスのない一連のアイデアとアーキテクチャの原則である。開発者が自分のプロジェクトでこれらの原則を採用し、実践するという意味で「使用」される。以下は、ソフトウェアエンジニアリングの実践において、これらの12の原則をどのように適用するかについての詳細な説明である。

中核概念：AIアプリケーションは何よりもまずソフトウェアである

いわゆる「AIアプリケーション」や「AIインテリジェンス」のコードの大部分は、伝統的で決定論的なソフトウェア工学のコードであるべきであり、LLMコールはパズルの1ピースに過ぎず、自然言語の理解や意思決定が必要とされる箇所で正確に使用されるという基本的な考え方を、始める前に理解しておくことが重要である。自然言語の理解、生成、意思決定。アプリケーション全体の制御を "リクエスト・ツール・ループ "のブラックボックスに渡す代わりに、開発者はLLMを特別な機能で呼び出すことができる関数として考えるべきである。

各原則の詳細な運用プロセス

原則1：自然言語によるツール呼び出し
これはインテリジェンスが外の世界と対話するためのエントリーポイントである。ユーザー入力（例えば、「昨日の北京の天気を調べてほしい」）を受け取ると、それを次のような関数呼び出しに変換する信頼できるメカニズムが必要になる。 search_weather(date="2025-07-21", city="北京").

• 操作方法LLMの "関数呼び出し "または "ツール使用 "機能を使います。モデルに送信されるリクエストでは、ユーザー入力だけでなく、呼び出すことができるツール（関数）のリストとそのパラメータの詳細なJSONスキーマ定義も提供します。モデルは、どの関数が呼び出され、どのパラメータが渡されるべきかを示すJSONオブジェクトを返します。あなたのコードは、このJSONを解析し、適切な関数を実行する責任を負います。

原則2：自分のプロンプトを持つ。
コード内で複雑なヒント単語を動的に生成しないでください。デバッグや反復が非常に困難になります。

• 操作方法プロンプトは静的な設定ファイルとして扱います。 .txt もしかしたら .md ファイル)を管理します。これらのキュー・ワード・テンプレートをコードに読み込み、変数を設定します。これらのキュー・ワード・ファイルをGitのようなバージョン管理システムに組み込むことは、まるで main.py もしかしたら index.js 同じだ。こうすることで、キュー・ワードに対するすべての変更を記録し、簡単にテストやロールバックを行うことができる。

原則3：コンテキスト・ウィンドウを所有する
コンテキスト・ウィンドウはLLMの唯一の "メモリー "である。入力の質がそのまま出力の質を決定する。過去のメッセージを無差別に詰め込んではいけない。

• 操作方法正確なコンテキスト構築戦略を実行する。LLMを呼び出す前に、あなたのコードは目の前のタスクの必要性に基づいてメッセージを注意深く選択し、組み合わせるべきである。これには、システムプロンプト、最も重要ないくつかの履歴メッセージ、関連文書の断片（RAGの結果）、ユーザーの最新の問題などが含まれます。目標は、LLMに、目の前の問題を解決するために必要な、最低限で最も重要な情報を提供することです。

原則4：ツールは構造化されたアウトプットにすぎない
これらの機能は "ツール "と呼ばれているが、別の見方をすれば、LLMにあなたが望む整形式のJSONを出力させる唯一の信頼できる方法である。

• 操作方法LLMを "ツール "と定義するのは、情報を抽出したり、分類したり、決定論的な出力形式を必要とするタスクを実行するためです。例えば、テキストから人名や会社名を抽出する必要がある場合、LLMを「ツール」として定義します。 extract_entities(person: str, company: str) このツールを「呼び出す」ためには、LLMはこのフォーマットで出力を生成しなければならない。

原則8：コントロールフローを所有する
これは多くの自動インテリジェンスフレームワークに反することだが、極めて重要なことだ。アプリケーションの「次に何をするか」は、ループの中でLLMによって完全に決定されるべきではない。

• 操作方法決定論的なコード（if/else、switch文、ステートマシンなど）を使って、中核となるビジネス・プロセスを書く。例えば、注文処理プロセスは次のようになる：接收订单 -> [LLM分类意图] -> if (查询) then call_query_api() else if (退货) then call_refund_api()ここでは、LLMは「tuを分類する」ステップだけを担当する。ここでは、LLMは "classify tu "のステップだけを担当し、すべてのプロセスはあなたのコードによって制御される。これによってシステムの動作が予測可能になり、デバッグが可能になる。

原則10：小規模で集中的なエージェント
すべてを処理できる「超知性」を構築しようとしてはいけない。

• 操作方法複雑なタスクを分解する。例えば、カスタマー・サポート・システムは、意図を認識するインテリジェンス、知識ベースを照会するインテリジェンス、注文を処理するインテリジェンスに分解できる。メインの制御フローコード（原則8）は、これらの間のルーティングとスケジューリングを担当します。各インテリジェンスには、それぞれにフォーカスしたキューワード（原則2）とツールセット（原則4）があります。

原則XII：エージェントをステートレス・リデューサーにする
これは、Reduxのようなフロントエンド・フレームワークのステート管理のアイデアを利用したもので、システムのテスト可能性と予測可能性を大幅に向上させることができる。

• 操作方法インテリジェンス、あるいはそのステップのひとつを、次のようなシグネチャを持つ純粋関数として実装する。 (currentState, event) => newState.
  • currentState は現在のアプリケーションのすべての状態である。
  • event は発生したばかりのイベントである（ユーザーからの新しいメッセージやAPIから返された結果など）。
  • 関数の戻り値 newState は更新された状態である。
    関数自体はステートレス（外部変数に依存しない）で、入力に基づいて出力を計算するだけである。そのため、ユニットテストを書くのがとても簡単です。 currentState 歌で応える event を組み合わせて、次のように主張する。 newState 期待に応えているかどうか。

これらの原則に従うことで、より動作が安定し、デバッグが容易で、既存のソフトウェアシステムと調和して動作するLLMアプリケーションを構築することができます。

アプリケーションシナリオ

1. 既存のSaaS製品にAI機能を追加する
   すでに安定したビジネスロジックを持つ成熟したSaaS製品（CRMやプロジェクト管理ツールなど）の場合、開発者はコアコードを書き換えることなく、段階的にAI機能を導入したいと考えている。例えば、原則1と原則8を使って、ユーザーの自然言語による指示（「来週締め切りのタスクを作成し、チャン・サンに割り当てる」）を既存のAPIの呼び出しに変換し、同時にコアとなるタスク作成ロジックの安定性を維持する。
2. エンドユーザー向けの高品質なAIアシスタントを開発
   お金を払う顧客と直接対話するAIアシスタントを開発する場合、信頼性とユーザーエクスペリエンスが重要です。一般的なフレームワークを直接使用すると、複雑なケースやエッジケースを扱ったときに予測不可能な動作になる可能性があります。これらの原則、特に原則III（コンテキストの習得）、原則VIII（制御フローの習得）、原則IX（エラーメッセージの圧縮）を適用することで、アシスタントが間違った答えを出したりクラッシュしたりするのではなく、原則VII（人間との対話）を通じて、問題を優雅に処理したり、必要なときに助けを求めたりすることを保証することができます。
3. AIプロトタイプの製品化
   多くのチームは、魅力的なプロトタイプ（デモ）を素早く構築するために高度なフレームワークを使用しますが、本格的な製品としてリリースする準備ができたとき、プロトタイプが実世界の複雑なシナリオで不安定である（品質が80%壊れない）ことに気づきます。この時点で、12-Factor Agentsは一連の「リファクタリング」ガイドラインを提供する。チームは、あいまいな制御フロー（loop-until-done）を明示的なステートマシンにリファクタリングしたり（原則8）、断片化されたプロンプトとステート管理を統一したり（原則2と5）など、これらの原則に従ったより堅牢なソフトウェアエンジニアリングの実践によって、プロトタイプコードを再検討し、刷新することができる。

品質保証

1. 12ファクター・エージェント」はインストール可能なソフトウェア・フレームワークですか？
   そうではない。LangChainやGriptapeのように直接pip installソフトウェアパッケージ。これは、信頼性の高いLLMアプリケーションを構築するために、開発者がコードや考え方をよりよく整理する方法を導くために設計された、設計哲学とアーキテクチャ原則のセットである。これは文書であり、方法論である。
2. なぜLLMに決めさせず、自分でコントロールの流れをコントロールするのか？それがインテリジェンスの素晴らしさではないか？
   これは、この方法論の核となる考え方のひとつである。LLMに制御フロー（すなわち「次に何をするか」）を完全に決定させることの魅力は、その柔軟性と新しいパスを発見する可能性にある。しかし、本番環境では、この不確実性は重大なリスクとデバッグの困難を伴います。アプリケーションに何か問題が発生したとき、その問題がLLMの意思決定にあるのか、ツールの実行にあるのかを特定するのは難しい。"12ファクター・エージェント "は、コアでリスクの高いビジネス・プロセスを決定論的なコード（例えば、ステートマシン）で定義し、プロセスの特定の時点でLLMを呼び出して局所的な意思決定（例えば、分類、情報の抽出など）を行うことを提唱している。これにより、システムの全体的な予測可能性と安定性を確保しながら、LLMの能力を活用することができる。
3. この一連の原則は、既存のAIフレームワークを一切使えないということですか？
   そんなことはない。これらの原則に従いながら、既存のフレームワークを使うことは絶対にできる。重要なのは、どのように使うかだ。フレームワークは、アプリケーション全体のフローを制御する「フレームワーク」ではなく、便利なツールを提供する「ライブラリ」だと考えればいい。例えば、フレームワークによって提供されるツールコールの解析機能を使うことができるが、メインの制御フローは自分で書く。あるいは、コンテキストを入力するためにフレームワークによって提供されるRAG（Retrieval Augmentation Generation）モジュールを使うことができるが、そのコンテキストの具体的な内容は、原則3に従って自分で正確に制御する。ポイントは、フレームワークにすべてをアウトソースするのではなく、アプリケーションの重要な部分の制御を維持することです。
4. この一連の原則は、AIのバックグラウンドを持たない従来のソフトウェア・エンジニアにとって従いやすいものなのだろうか？
   あまりにも簡単なので、この一連の原則は優秀なソフトウェア・エンジニアのために作られたとさえ言えるかもしれない。その多く（バージョン管理、状態管理、モジュール化、決定論的制御フローなど）は、ソフトウェア工学のベストプラクティスである。この原則は、エンジニアにまったく新しい確率的プログラミングパラダイムを習得させるのではなく、すでに慣れ親しんだ信頼できるエンジニアリングの考え方でLLMをナビゲートすることを奨励している。これは、LLMを強力だが注意深く管理された「コンポーネント」に「降格」させ、エンジニアが自分の慣れ親しんだ領域で作業できるようにするものである。