12ファクターAIエージェント：効果的でスケーラブルなAIシステムの構築

効果的なAIエージェントとは？

本題に入る前に、「AIエージェント」とは何かを明確にしましょう。AIエージェントとは、自然言語によるリクエストを解釈し、コンテキストに基づいて意思決定を行い、ツールやAPIを通じて特定のアクションを実行できるシステムです。さらに、首尾一貫したやりとりを継続できる能力も備えています。

最も強力なエージェントは、言語モデルの推論力と決定論的コードの信頼性を組み合わせています。しかし、そのバランスを取るためには慎重な設計判断が必要であり、それこそがここで紹介する「ファクター」の役割です。

堅牢なAIエージェントを構築する12の要素

1. 自然言語からツールコールへの変換を極める

自然言語リクエストを構造化されたツールコールへ変換する能力は、エージェント機能の中核です。たとえば「2月のAI TinkerersミートアップでTerriへ750ドルの支払いリンクを作成して」といった単純な指示も、適切なAPIコールに変換できます。

画像URL

{
  "function": {
    "name": "create_payment_link",
    "parameters": {
      "amount": 750,
      "customer": "cust_128934ddasf9",
      "product": "prod_8675309",
      "price": "prc_09874329fds",
      "quantity": 1,
      "memo": "Hey Jeff - see below for the payment link for the February AI Tinkerers meetup"
    }
  }
}

この仕組みを確実に実行するには、言語モデルからの構造化出力を決定論的なコードで処理することが重要です。APIペイロードは必ず実行前に検証し、LLMから一貫したJSON形式が返るように設計しましょう。

2. プロンプトを完全に自分で管理する

プロンプトはアプリケーションとLLMのインターフェースであり、一級コードとして扱うべきです。プロンプトを抽象化するフレームワークは便利に見えますが、多くの場合LLMへの指示内容が不透明になり、微調整が難しくなります。

その代わりに、プロンプトを明示的に自分で記述し直接管理しましょう：

function DetermineNextStep(thread: string) -> DoneForNow | ListGitTags | DeployBackend | DeployFrontend | RequestMoreInformation {
  prompt #"
    {{ _.role("system") }}
    あなたはフロントエンドおよびバックエンドのデプロイ管理を行う有能なアシスタントです。
    ...
    {{ _.role("user") }}
    {{ thread }}
    次のステップは何ですか？
  "#
}

このアプローチの利点：

• 用途に合わせた的確な指示を自由に書ける
• プロンプトも他のコード同様にテストや評価が可能
• LLMに渡る内容が完全に把握できる
• パフォーマンス指標に基づいて柔軟に改善できる

3. コンテキストウィンドウを戦略的に設計する

コンテキストウィンドウはLLMの入力として機能し、プロンプト・会話履歴・外部データを含みます。このウィンドウを最適化することで性能やトークン効率が向上します。

画像URL

標準的なメッセージ形式から一歩進み、情報密度の高いカスタム構造にしましょう：

<slack_message>
    From: @alex
    Channel: #deployments
    Text: Can you deploy the backend?
</slack_message>
<list_git_tags>
    intent: "list_git_tags"
</list_git_tags>
<list_git_tags_result>
    tags:
      - name: "v1.2.3"
        commit: "abc123"
        date: "2024-03-15T10:00:00Z"
</list_git_tags_result>

この方法のメリット：

• コンパクトな形式でトークン消費を削減
• LLMに送る前に機密データのフィルタリングが容易
• LLMの理解を高める柔軟なフォーマット実験が可能

4. ツールを構造化出力として実装する

ツールの本質は「LLMから得たJSON出力をトリガーとして、コード側で決定論的なアクションを実行する」ことです。これによりAIの意思決定と実行ロジックを明確に分離できます。

ツールスキーマを明確に定義：

class CreateIssue {
  intent: "create_issue";
  issue: {
    title: string;
    description: string;
    team_id: string;
    assignee_id: string;
  };
}

class SearchIssues {
  intent: "search_issues";
  query: string;
  what_youre_looking_for: string;
}

LLMのJSON出力を確実にパースし、決定論的なコードでアクションを実行、そして結果をコンテキストにフィードバックして反復ワークフローを実現します。

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

多くのエージェントフレームワークは「実行状態（プロセスの現在のステップなど）」と「ビジネス状態（ツールコール履歴や結果）」を分離しますが、これは不要な複雑さをもたらします。

すべての状態をコンテキストウィンドウ内に保存し、イベントの時系列から実行状態を推論しましょう：

<deploy_backend>
    intent: "deploy_backend"
    tag: "v1.2.3"
    environment: "production"
</deploy_backend>
<error>
    error running deploy_backend: Failed to connect to deployment service
</error>

この統合アプローチの利点：

• 状態の単一ソースでシンプルに管理
• 履歴が一箇所にまとまるのでデバッグが容易
• スレッドをロードするだけでどこからでもリカバリー可能

AIエージェントを本番運用へ

6. 起動・一時停止・再開のためのAPI設計

本番運用レベルのエージェントは、外部システムとシームレスに統合し、長時間タスクの一時停止やWebhooksなどのイベントでの再開が必要です。

エージェントの起動・一時停止・再開を可能にするAPIを実装し、各操作間で堅牢に状態保存しましょう。これにより：

• 非同期ワークフローへの柔軟な対応
• Webhookや他システムとのクリーンな統合
• 中断後も状態を保持したまま確実に再開

7. ツールコールを通じた人間との協働

AIエージェントは重要な意思決定や曖昧な状況で人間の入力が必要です。構造化ツールコールを使えば、このやり取りもシームレスに：

class RequestHumanInput {  
  intent: "request_human_input";  
  question: string;  
  context: string;  
  options: {  
    urgency: "low" | "medium" | "high";  
    format: "free_text" | "yes_no" | "multiple_choice";  
    choices: string[];  
  };  
}

画像URL

この設計で、やり取りの種類や緊急度を明確に指定でき、複数ユーザーからの入力もサポート。APIと組み合わせて耐障害性の高いワークフローを実現します。

8. エージェントのフローを制御する

カスタム制御フローにより、人間の承認待ちで一時停止したり、結果をキャッシュしたり、レート制限を実装するなど、用途に合わせてエージェントの挙動を最適化できます。

画像URL

async function handleNextStep(thread: Thread) {
  while (true) {
    const nextStep = await determineNextStep(threadToPrompt(thread));
    if (nextStep.intent === 'request_clarification') {
      await sendMessageToHuman(nextStep);
      await db.saveThread(thread);
      break;
    } else if (nextStep.intent === 'fetch_open_issues') {
      const issues = await linearClient.issues();
      thread.events.push({ type: 'fetch_open_issues_result', data: issues });
      continue;
    }
  }
}

このアプローチで得られること：

• 重要なアクション前に人間のレビューで一時停止可能
• ログ取得・キャッシュ・要約などのカスタマイズが容易
• 長時間タスクの確実な処理

9. コンテキストにエラーを集約し自己修復化

エラーをコンテキストウィンドウに直接含めることで、AIエージェントは失敗から学び、対応を調整できます：

try {
  const result = await handleNextStep(thread, nextStep);
  thread.events.push({ type: `${nextStep.intent}_result`, data: result });
} catch (e) {
  thread.events.push({ type: 'error', data: formatError(e) });
}

この仕組みを有効にするには：

• 無限ループ回避のためリトライ回数を制限
• 失敗が続く場合は人間にエスカレーション
• LLMが理解しやすい形でエラーを明確に整形

アーキテクチャのベストプラクティス

10. 小さくフォーカスしたエージェントを構築

3～20ステップ程度の小さなエージェントはコンテキストウィンドウも管理しやすく、LLMの性能・信頼性が向上します。

• 各エージェントの役割が明確で分かりやすい
• フォーカス喪失のリスクが減少
• 個別機能ごとのテスト・検証が容易

画像URL

今後LLMの進化により、こうした小さなエージェントもスコープを拡大しつつ品質を維持し、長期的なスケーラビリティを確保できます。

11. 複数ソースからのトリガーを可能に

Slack、メール、イベントシステムなど、さまざまなチャネルからエージェントを起動できるようにし、ユーザーが普段使う場所でアクセス可能にしましょう。

各チャネルからエージェントを起動し、同じ媒体でレスポンスするAPIを実装。これにより：

• ユーザーの好むプラットフォームへの統合で利便性向上
• イベント駆動型自動化ワークフローへの対応
• 重要な操作での人間承認ワークフローも実現

12. エージェントをステートレスリデューサーとして設計

エージェントを「入力コンテキストを出力アクションへ変換するステートレスな関数」として扱うことで、状態管理がシンプルになり、予測可能性・デバッグ容易性が向上します。

画像URL

この考え方では、エージェントは内部状態を保持せず純粋関数として動作し、次のメリットが得られます：

• 入力が同じなら必ず同じ出力となる予測可能な挙動
• コンテキスト履歴を追うことで問題の原因を特定しやすい
• テストや検証がシンプル

未来を見据えた構築

AIエージェント分野は急速に進化していますが、これらの基本原則は今後も有効です。まずは小さくフォーカスしたエージェントで着実に価値を提供しつつ、将来の進化にも適応できるシステムを目指しましょう。

最も効果的なAIエージェントは、言語モデルの推論力と決定論的コードの信頼性の両立により実現します。この12ファクターが、そのバランスを取るための指針となります。

FlowHuntが12ファクター手法をどう活用したか

FlowHuntでは、これらの原則を実践し、顧客向けのワークフロー自動化を自動生成するAIエージェントを開発しました。信頼性が高く本番運用に耐えるシステムを構築するため、12ファクター手法をどのように適用したかをご紹介します。