第六段階：AIプロジェクト実践と本番環境へのデプロイ

本番環境で使用可能なLLM駆動型ソフトウェアを構築するための12のコア原則。AIアプリケーションのプロトタイプから本番環境への移行における重要なエンジニアリング課題の解決に焦点を当てています。

Start Learning AI →
ProductionAILLMEngineeringAIAgentsGitHubTextFreeEnglish

12 Factor Agents - 信頼性の高いLLMアプリケーションを構築するための12の原則

概要

12 Factor Agents は、Dex HorthyとHumanLayerチームによって開発された、本番環境で使用可能なLLM駆動型ソフトウェアを構築するための原則的な方法論です。

背景と動機

なぜこれらの原則が必要なのか？

著者は100人以上のSaaS開発者（主に技術系創業者）と対話した結果、ほとんどのAIエージェント開発が「70-80%の品質ボトルネック」に直面していることを発見しました。

  1. 初期の迅速な進捗：既存のフレームワークを使用して、機能の70-80%に迅速に到達する
  2. 品質のボトルネック：顧客向け機能としては80%では不十分であると判明する
  3. フレームワークの限界：80%を超えるには、フレームワーク、プロンプト、プロセスなどをリバースエンジニアリングする必要がある
  4. ゼロからの再構築：最終的にフレームワークを捨てて最初からやり直さざるを得なくなる

核となる洞察

  • 成功した本番レベルの「AIエージェント」のほとんどは、実際にはそれほど「エージェント的」ではない
  • それらは主に、重要なポイントでLLMを巧みに使用する、精巧に設計されたソフトウェアシステムである
  • 顧客に高品質なAIソフトウェアを最速で提供する方法は、小さくモジュール化された概念を採用し、既存の製品に統合することである

12の核となる原則

Factor 1: 自然言語からツール呼び出しへ

LLMの核となる超能力は、自然言語を構造化データ（JSON）に変換することです。すべてのエージェント操作は、この基本的な変換から始めるべきです。

// コアパターン
const response = await llm.generateToolCall(userMessage, availableTools);
// response は構造化されたJSONであり、自由形式のテキストではない

Factor 2: プロンプトを所有する

プロンプトを使い捨ての入力ではなく、重要なバージョン管理されたコード資産として扱います。

  • アプリケーションのコードベースでプロンプトを管理する
  • 体系的なテスト、デプロイ、ロールバックをサポートする
  • 一貫性、再現性、制御された進化を保証する

Factor 3: コンテキストウィンドウを所有する

LLMのコンテキストウィンドウを能動的かつ意図的に管理します。

  • コンテキストウィンドウに現在のタスクに直接関連する情報のみが含まれるようにする
  • 「コンテキストドリフト」を防ぐために不要なデータを剪定する
  • LLMのパフォーマンスを向上させ、トークン使用量を削減する

Factor 4: ツールは単なる構造化出力である

「ツール」をLLM出力の構造化されたJSONとして扱い、検証します。

// ツール呼び出しは単なるJSONスキーマ検証である
const toolCall = validateToolCall(llmOutput, toolSchema);
const result = await executeValidatedTool(toolCall);

Factor 5: 実行状態とビジネス状態を統一する

LLMの内部「実行状態」が、アプリケーションの実際の「ビジネス状態」と一貫していることを確認します。

  • LLMが古い情報や誤った情報に基づいて操作するのを防ぐ
  • ハルシネーションや無効な操作を避ける
  • 実行状態をビジネス状態の隣に永続化する

Factor 6: シンプルなAPIで起動/一時停止/再開する

ライフサイクル管理をサポートする、明確なプログラミングインターフェースを持つLLMエージェントを設計します。

interface AgentControl {
  launch(config: AgentConfig): Promise<AgentInstance>;
  pause(instanceId: string): Promise<void>;
  resume(instanceId: string): Promise<void>;
}

Factor 7: ツール呼び出しで人間と連携する

人間とのインタラクションを、ファーストクラスのツール呼び出しとして扱います。

  • リスクの高いステップは人間のレビューにルーティングする
  • 人間のフィードバックを構造化された入力としてシステムに戻す
  • シームレスな人間とAIの協調ワークフロー

Factor 8: 制御フローを所有する

制御フローを通常のコードまたは独自のワークフローエンジン内に保持します。

  • 明示的なOODAループ（Observe-Orient-Decide-Act）を実行する
  • ネストされたプロンプトではなく、収束ヒューリスティックを使用する
  • LLMに複雑な制御フローを管理させない

Factor 9: エラーをコンテキストウィンドウに圧縮する

フィードバックループを閉じるために、エラー情報を次のプロンプトに圧縮します。

  • LLMがエラーから学習し、回復できるようにする
  • 構造化されたエラー情報を提供する
  • 自己修復能力をサポートする

Factor 10: 小さく、焦点を絞ったエージェント

巨大なモノリシックなチャットボットではなく、小さく単一目的のエージェントを構築します。

// 良い実践例：焦点を絞った小さなエージェント
class EmailSummaryAgent {
  async summarize(email: Email): Promise<Summary> { /* ... */ }
}

class PriorityClassificationAgent {
  async classify(email: Email): Promise<Priority> { /* ... */ }
}

Factor 11: どこからでもトリガーし、ユーザーがいる場所でサービスを提供する

ユーザーがすでに作業している場所からエージェントをトリガーします：CLI、webhook、cronなど。

  • 既存のワークフローに統合する
  • 多様なトリガーメカニズム
  • ユーザーフレンドリーなアクセスポイント

Factor 12: エージェントをステートレスなリデューサーにする

アプリケーションが状態を管理し、エージェントはステートレスに保ちます。

// ステートレスエージェントパターン
class StatelessAgent {
  step(state: State): Promise<State> {
 
  }
}

技術アーキテクチャパターン

コアループの簡素化

各エージェントは本質的に次のようになります。

const prompt = "Instructions for next step selection"; // 次のステップ選択のための指示
const switchFunction = (json) => routeToFunction(json); // JSONを関数にルーティングする
const context = manageWhatLLMSees(); // LLMが見るものを管理する
const loop = whileNotDone(); // 完了するまでループする

従来のDAGとの違い

  • 従来のDAG：ソフトウェアエンジニアが各ステップとエッジケースをコーディングする
  • エージェントアプローチ：エージェントに目標と一連の変換を与え、LLMにリアルタイムでパスを決定させる
  • 実際の状況：最も成功した実装は、より大きな決定論的DAG内でエージェントパターンを巧みに使用している

適用シナリオ

最適なシナリオ

  • 自然言語理解が必要な構造化タスク
  • 人間とAIの協調が必要なワークフロー
  • 複雑な多段階ビジネスプロセス
  • 高い信頼性が求められる本番環境

不適切なシナリオ

  • シンプルな決定論的タスク（直接コードを書く方が良い）
  • 100%の正確性が求められるミッションクリティカルなタスク
  • 極度にリソースが制約された環境

実装の推奨事項

段階的な採用

  1. 小さく始める：現在の課題に関連する原則を1つ選択する
  2. 実装と観察：改善効果を確認する
  3. 徐々に追加する：その後、別の原則を追加する
  4. 継続的な最適化：継続的に改善と調整を行う

技術スタックの推奨

  • 言語：TypeScript（著者推奨、Pythonなどの他の言語もサポート）
  • 主要ライブラリ：BAML（スキーマアライメント解析用）
  • デプロイ：クラウドネイティブおよびKubernetesをサポート

関連リソース

公式リソース

参考文献

まとめ

12 Factor Agentsは、真に本番環境で使用可能なLLMアプリケーションを構築するための体系的なアプローチを提供します。それは、より魔法のようなフレームワークを構築することではなく、LLMの能力に優れたソフトウェアエンジニアリングの実践を適用することを強調しています。核となる理念を忘れないでください：エージェントはソフトウェアであり、ソフトウェアとして扱うことで、信頼性、保守性、そして競合他社には真似できない能力で報われるでしょう。