AIエージェント設計
核となる哲学
エージェントは魔法ではありません — 入力、出力、メモリ、ツール、そして決定ロジックを持つシステムです。プロダクションソフトウェアと同じ厳格さで設計してください。すべてのエージェントには明確な目的、定義された境界、そして明示的な障害モードが必要です。
エージェント設計の原則
1. 行動する前に意図を明確にする
エージェントは、ユーザーの意図が曖昧な場合 — 不可逆的なアクションを実行する前に — 明確化の質問をしなければなりません。以下のパターンを使用します：
- 目標は明確か？そうでなければ、焦点を絞った質問を1つする。
- 制約は既知か？（スコープ、出力形式、データソース）
- 成功とはどのような状態か？
2. コードの前に仕様書を作成する
エージェントロジックを書く前に、仕様書またはタスクリストファイルを生成します：
- エージェントの役割と責任を定義する
- アクセスする必要があるすべてのツールをリストアップする
- 入力/出力の契約を定義する
- 障害モードとフォールバック動作を特定する
- その後、コードを書く
3. 単一責任
各エージェントは一つのことをうまく行うべきです。汎用エージェント1つよりも、特化したエージェントのチームを優先します。
オーケストレーションパターン
| パターン | 使用すべき時 | 説明 |
|---|---|---|
| Sequential (順次) | 線形パイプライン | エージェントが固定順序で連鎖する（ドラフト → レビュー → 公開） |
| Supervisor (スーパーバイザー) | 複雑なマルチモジュールタスク | リードエージェントが専門ワーカーにルーティングする |
| ReAct (リアクト) | 自律的な問題解決 | 推論（思考）+ 行動（ツール使用）を組み合わせる |
| Group Chat (グループチャット) | 協調タスク | 人間による監視付きのマルチエージェント通信 |
| DAG (有向非巡回グラフ) | ステートフルワークフロー | 循環的でステートフルなオーケストレーションのための有向非巡回グラフ |
フレームワーク選択ガイド
| フレームワーク | 最適な用途 | ステータス |
|---|---|---|
| LangGraph | 複雑なステートフルエージェント、循環的ワークフロー、マルチエージェントオーケストレーション、プロダクショングレード | ✅ アクティブ — GA 2025年5月 |
| LangChain | シンプルなRAGパイプライン、線形ワークフロー、迅速なプロトタイピング | ✅ アクティブ — RAGに使用、エージェントには非推奨 |
| CrewAI | ロールベースのマルチエージェントチーム（「マネージャー」、「リサーチャー」、「ライター」） | ✅ アクティブ |
| Microsoft Agent Framework | Azureエコシステムにおけるエンタープライズエージェント — AutoGen + Semantic Kernelを置き換え | ✅ アクティブ — パブリックプレビュー2025年10月、GA目標2026年第1四半期 |
| AutoGen | レガシー — 依然として動作するが新機能はなし | ⚠️ 2025年10月よりメンテナンスモード |
| カスタム (MCP) | オープンスタンダードによる軽量でポータブル、相互運用可能なエージェントツール | ✅ アクティブ |
LangChain vs LangGraph — どちらを使うべきか
LangChainチームは現在、以下のように明確に分割することを推奨しています：
- LangGraph → エージェント向け：ステートフル、循環的、マルチエージェント、長時間実行タスク
- LangChain → RAGと線形パイプライン向け：シンプルなドキュメントQ&A、ステップバイステップ変換
LangGraphはLangChain上に構築されています — 両方を一緒に使用でき、LangChainから始めて、より多くの制御が必要になった場合にLangGraphに移行できます。
RAGパイプライン設計
標準的なRAGフロー
ユーザークエリ → クエリの埋め込み化 → ベクトル検索 → チャンク取得 → プロンプト拡張 → LLM → 応答
チャンキング戦略（2026年ベストプラクティス）
- セマンティックチャンキングを使用 — 文字数ではなく意味で区切る
- チャンクサイズ：精度重視の場合は256～512トークン、ナラティブコンテンツの場合は1024トークン
- 常にメタデータを含める：ソース、ページ、セクション、タイムスタンプ
ハイブリッド検索（推奨）
密ベクトル（セマンティック）+ 疎ベクトル（キーワード）を組み合わせて最適な再現率を実現：
最終スコア = α × 密スコア + (1 - α) × 疎スコア
ベクトルデータベース選択
| DB | 最適な用途 |
|---|---|
| pgvector | 既存のPostgreSQLスタック、シンプルなユースケース |
| Pinecone | マネージド、プロダクション規模、最小限の運用 |
| Weaviate | マルチモーダル、ハイブリッド検索組み込み |
| Milvus | 高性能、セルフホスト、大規模 |
| Chroma | ローカル開発、プロトタイピング |
エージェントメモリアーキテクチャ
| タイプ | 説明 | 実装 |
|---|---|---|
| コンテキスト内 | 現在の会話ウィンドウ | チャット履歴配列 |
| 外部短期 | セッションスコープのメモリ | Redis / インメモリストア |
| 外部長期 | セッションをまたぐ永続的メモリ | ベクトルDB + メタデータ |
| エピソード記憶 | 過去のやり取りの要約 | 要約チェーン → ベクトルストア |
コンテキスト腐敗警告： 長いコンテキストウィンドウは、時間の経過とともにエージェントの品質を低下させます。関連性を維持するために、N回のターンごとに要約ステップを実装してください。
ツール使用と関数呼び出し
ツール定義パターン
すべてのツールには以下が必要です：
name: 説明的なツール名
description: このツールを使用すべき時とその機能（明示的に記述）
parameters:
- name: パラメータ名
type: 文字列
description: このパラメータが期待するもの
required: true
ツール使用のベストプラクティス
- 可能な限りツールは冪等であるべき
- 次のステップに渡す前に常にツール出力を検証する
- 外部ツール呼び出しにはタイムアウトとリトライを実装する
- デバッグのためにすべてのツール呼び出しをログに記録する
エージェント通信パターン
意図明確化プロトコル
エージェントが曖昧なリクエストを受け取った場合：
- 曖昧さを特定する — 具体的に何が不明確か？
- 1つの質問をする — すべてではなく、最も重要な質問を一つ
- デフォルトを提案する — 「特に指示がなければXと仮定します」
- 不可逆的なアクションの前に確認する — 削除、公開、送信の前には必ず確認する
進捗報告
長時間実行タスクの場合、エージェントは以下を報告する必要があります：
[ステップ 1/4] ドキュメントを取得中... ✓
[ステップ 2/4] チャンキングと埋め込み化中... ✓
[ステップ 3/4] ベクトルストアに問い合わせ中...
エラー通知
✗ ツールが失敗しました: [ツール名]
理由: [具体的なエラー]
フォールバック: [代わりに行っていること]
MCP（モデルコンテキストプロトコル）
MCPは、エージェントを外部ツールやデータソースに接続するためのオープンスタンダードです。ポータブルで相互運用可能なエージェントツールを構築する際に使用します。
MCPサーバー構造
my-mcp-server/
├── server.py (または index.ts)
├── tools/
│ └── my_tool.py
└── README.md
MCPを使用すべき時 vs 直接統合
- MCPを使用：ツールを複数のエージェント/プラットフォームで再利用可能にする必要がある場合
- 直接統合を使用：プロジェクト固有の単発的なツール実装の場合
詳細なMCPサーバー実装ガイダンスについては、mcp-builderスキルを参照してください。
セキュリティと安全性
- サンドボックス化なしにエージェントが任意のコードを実行することを決して許可しない
- すべてのLLM API呼び出しにレート制限を実装する
- ツールに渡す前にすべての入力を検証およびサニタイズする
- 監査可能性のためにすべてのエージェントの決定をログに記録する
- 暴走するトークンコストや再帰ループを防ぐためのガードレールを実装する
- システムプロンプトインジェクション対策を使用する — ユーザー入力をシステム指示から明確な区切り文字で分離する
回復力のあるエージェント設計（自己回復）
エージェントは本番環境で失敗します。最初から復旧を考慮して設計してください。
検証と再試行ループ（LoopAgentパターン）
出力を生成 → 出力を検証 → 無効な場合：フィードバック + 再生成
最大反復回数：3 ← 無限ループを防ぐサーキットブレーカー
計画・検証・実行・観察・再計画
計画: 計画を生成し、行動する前に実現可能性を確認
実行: 行動を起こす
観察: 成功したか？出力を確認し、テストを実行
再計画: 観察で失敗が示された場合 → 調整して再試行
停止: 最大再試行回数に達した場合 → 失敗を明確に報告し、助けを求める
エージェントフォールバック階層
主要アプローチが失敗 → 代替アプローチを試行
代替アプローチも失敗 → 開発者に明確化を依頼
明確化がない場合 → 安全なデフォルトアクションまたは正常停止
提示前の出力検証
- 生成されたコードを提示する前にテスト/ lintを実行する
- 出力形式が要件と一致していることを確認する
- ジェネレーターの出力をチェックするために別のバリデーターステップ（異なるモデルまたはプロンプト）を使用する
- 未検証の出力を完了したものとして提示しない
エージェント用サーキットブレーカー
暴走動作を防ぐためにハードリミットを設定します：
- タスクあたりの最大ツール呼び出し反復回数（例：10）
- セッションあたりの最大トークン消費量
- 失敗ステップあたりの最大再試行回数（例：3）
- ツール呼び出しあたりのタイムアウト
完全な回復力の哲学とコードパターンについては、self-healing-mindsetスキルを参照してください。