# AIエージェントをソフトウェアに組み込むプラクティス # Synchronous Edge Agent｜同期エッジ 🎯 キャッチーなメッセージ LLMエージェント、まず「同期で返せないか？」を考えていますか？ 非同期キューやチェックポイントに飛びつく前に、シンプルな同期HTTPで完結できないか検討しましょう。実際のユースケースの大半は、それで十分です。 🔥 解決する課題 エージェントアーキテクチャの議論はすぐに非同期キュー・チェックポイント・オーケストレータへ進みがちです。しかし多くのタスクは「LLM1回＋軽いツール」で済みます。軽量タスクに重い実行基盤を持ち込むと、運用コスト・デプロイ複雑性・デバッグ難度が不必要に跳ね上がります。 💡 提案パターン Synchronous Edge Agent（同期エッジ）は、単発のLLM推論と軽量ツール0〜2回を1つの同期HTTPリクエスト内で完結させる、最もシンプルな実行方式です。状態はインコンテキストのみで、チェックポイントもキューも不要です。テキスト分類・情報抽出・単純Q&A・要約・構造化出力生成など「数秒で終わる確実な処理」に最適です。タイムアウトはLLM呼び出し単位でp99実測値に基づいて設定し、モデル選択もレイテンシ予算の関数として決定します。迷ったらまずここから始めてください。 ✅ 選定条件 使うとき： - 処理が概ね5〜10秒以内に終わる（対面）、またはAPI連携で30秒以内 - LLM呼び出しは1回、ツール呼び出しは0〜2回の軽量処理 - 途中再開や人間承認が不要 使わないとき： - 処理が30秒を超えうる、または所要時間が読めない場合 - 複数ツールの多段呼び出しや計画・反省ループが必要な場合 - 不可逆な副作用（決済・データ削除等）を伴う場合 ⚠️ 落とし穴 - タイムアウトはHTTPサーバ全体でなくLLM呼び出し単位で設定すること。全体タイムアウトだけではLLMがハングしてワーカースレッドを占有し続けます - 同期枠内でのリトライは0〜1回に限ること。リトライを重ねるとクライアントが先にタイムアウトします - サーバーレス環境ではコールドスタートがレイテンシ予算を食うため、Provisioned Concurrencyやウォームアップで対処が必要です 🔧 実装方針 - クライアントからのHTTPリクエストをAPI Gateway経由でハンドラが受け取り、1つのリクエスト-レスポンスサイクル内で処理を完結させます。外部キューやチェックポイントストアは登場しません - タイムアウトはHTTPサーバ全体ではなくLLM呼び出し単位で設定し、その値はlatency_budgetから導出します。p95/p99の実測値に基づいて調整します - モデル選択もレイテンシ予算の関数として決定します。分類・抽出には軽量モデル、生成にはミッド〜フラグシップを選びます - 構造化出力（JSON Schema等）を使い、レスポンスの軽量検証を常にONにします。意味検証はレイテンシに余裕がある場合のみ追加します - 対面UIで生成が長文になる場合はSSEストリーミングを併用し、体感レイテンシを短縮します #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # Dry-run & Commit｜差分提示してから実行 🎯 LLMがハルシネーションしたパラメータで決済が走る。それ、dry-runで防げます。 Terraformの plan → apply と同じ発想をエージェントのツール呼び出しに適用。「何が変わるか」を見てから実行する二相プロトコルです。 🔥 解決する課題 LLMはハルシネーションで意図しないパラメータを生成することがあり、ツール呼び出しは副作用を伴います。この二つが掛け合わさると、存在しないリソースIDや桁違いの金額で不可逆な操作が実行されるリスクが生まれます。dry-runなしの直接実行では、人間が「エージェントが何をしようとしているか」を確認する手段がなく、問題は事後にしか検出できません。 💡 提案パターン 副作用を伴う操作を「計画（dry-run）→ 差分提示 → 承認 → 実行（commit）」の二相で行います。dry-runフェーズではシステムを一切変更せず差分だけを計算し、承認を得てからcommitフェーズで書込を実行します。承認方式はリスクに応じて段階化し、高リスクは人間承認、中リスクはポリシー自動検証、低リスクは自動承認とします。planにはTTLを設け、状態変化が起きていたら再生成を強制します。 ✅ 選定条件 使うとき： - 不可逆な操作（データ削除、外部API書込、課金処理）をエージェントが実行する - 誤操作が金銭的・法的・運用的な実害を生みうる - 差分を評価するための数秒〜数分の待機が許容される 使わないとき： - 全操作が読み取り専用の場合 - 全操作が可逆かつ低コストの場合（チャット応答生成など） - レイテンシ制約が極めて厳しく承認待ちが許容されない場合 ⚠️ 落とし穴 - planとcommitの間に状態が変わるTOCTOU問題があります。commit時に前提条件を再検証する設計が必須です - 外部APIがdry-runモードを提供していない場合は、パラメータ検証とシミュレーションで代替し「推定」であることを明示します - commitエンドポイントがplan IDなしで呼べると、dry-runを迂回できてしまいます 🔧 実装方針 - ツール実行をdry-run（差分計算のみ）→承認→commit（実行）の三段階パイプラインとして構成し、各フェーズを独立したエンドポイントに分離します - planオブジェクトに変更前後の値・影響範囲・ロールバック手順・前提条件のハッシュを含め、commit時に前提条件の再検証（TOCTOU対策）を行います - commitエンドポイントは有効なplan IDと承認トークンの両方を必須パラメータとし、直接呼び出しによるdry-run迂回を構造的に防止します - planにTTLを設定し、期限切れの場合は再planを強制することで、古い差分に基づく実行を防ぎます #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # 読取自由・書込ゲート 🎯 「全ツール呼び出しに承認を求める」設計は、承認疲れで自壊します。 読取と書込を非対称に扱うだけで、安全性と生産性の両立が実現できます。承認すべき操作に人間の注意を集中させましょう。 🔥 解決する課題 エージェントのツール呼び出しには副作用のある操作とない操作が混在しています。すべてに一律の承認を求めると、読取が大半を占める実運用では承認疲れが発生し、肝心の書込操作の承認が形骸化してしまいます。かといってすべてを自由にすれば、不可逆な書込操作で取り返しのつかない変更が走るリスクが残ります。 💡 提案パターン ツール呼び出しを「読取（検索・取得・参照）」と「書込（作成・更新・削除・送信）」に二分し、読取は自由に許可、書込にだけ認可・検証・承認・監査のゲートを設けます。R/W分類はツール定義時に静的に付与し、LLMの判断には委ねません。書込ゲートの厳格度は可逆性で段階化し、不可逆操作（メール送信・決済）は人間承認必須、可逆操作（下書き保存）はポリシー検証のみとします。これにより承認疲れを劇的に減らしつつ、副作用の安全性を維持できます。 ✅ 選定条件 使うとき： - 読取と書込が混在し、読取が多数を占める - 不可逆な書込操作（メール送信、決済、本番DB変更）が含まれる - 承認疲れを防ぎ、人間のレビュー帯域を高リスク操作に集中させたい 使わないとき： - 読取自体が機密データへのアクセスを含む場合（個人情報検索など）は、読取にも認可が必要 - 全操作が読取専用で書込がそもそも存在しない場合 - 実験環境で全操作が可逆かつ低コストな場合 ⚠️ 落とし穴 - R/W分類をLLMに任せてはいけません。インジェクションで書込ツールが「読取」と判断される経路を作ります - 「読取だが副作用がある」操作（API呼び出し回数カウント、閲覧履歴記録など）を見落とさないでください - 可逆な書込と不可逆な書込を同じ厳格度にすると、承認疲れの問題が再発します 🔧 実装方針 - ツール定義時にtype（read/write）とgate種別（none/auto/human_approval）を静的に付与し、実行時にLLMが分類を変更できない構造にします - 読取パスではメタデータのみをログに記録し、書込パスでは入力検証・ゲート判定・実行・監査ログの全量記録をパイプラインとして実装します - 書込ゲートの厳格度をreversibleフラグで段階化し、不可逆操作にはdry-runの前段必須化も組み合わせます - ゲート判定ロジックはゲートウェイ層のコードで強制し、プロンプトによる制御は一切使用しません #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # ツールゲートウェイ・MCP仲介 🎯 エージェントのツール呼び出し、全部「野良API」になっていませんか？ AIエージェントが複数のツールやMCPサーバを直接呼び出す構成は、認可漏れ・二重実行・監査不能の温床です。単一のゲートウェイを挟むだけで、セキュリティの一貫性が劇的に変わります。 🔥 解決する課題 エージェントが外部ツールを直接叩く構成では、認可・レート制限・ログがツールごとにバラバラになります。プロンプトインジェクションで悪意ある引数が混入しても個別ツール側では弾けず、権限昇格や意図しない操作が起きえます。さらに呼び出しログが分散し、「誰の権限で・なぜこのツールが呼ばれたか」の事後追跡コストが跳ね上がります。 💡 提案パターン 全ツール呼び出しを単一のゲートウェイ層に集約し、認可・入力サニタイズ・レート制限・監査ログを一元管理します。タスク種別やユーザ権限に応じてツールを動的にスコーピングし、LLMに不要なツールを見せない設計にします。書込系ツールには操作単位の細粒度認可とHITL承認を、読取系にはカテゴリ単位の緩い認可を適用する非対称ポリシーが鍵です。ツールの追加・削除もゲートウェイの設定変更だけで完結し、エージェント本体のコード変更は不要になります。 ✅ 選定条件 使うとき： - エージェントが複数ツールを呼び出し、少なくとも一つが副作用を持つ - ユーザ入力や外部データがツール引数に含まれうる（input_trustが低い） - 「どのツールが・どの引数で・誰の権限で呼ばれたか」の説明義務がある 使わないとき： - ツールが1つだけかつ読み取り専用で、ゲートウェイのオーバーヘッドが見合わない - 全ツールが社内信頼済みの実験環境で、まずプロトタイプ速度を優先したい ⚠️ 落とし穴 - ゲートウェイ自体が単一障害点になります。ヘルスチェックと縮退モード（読取のみ許可など）の設計が必須です - 認可やサニタイズをプロンプトで行ってはいけません。「このツールは使わないで」はインジェクションで迂回されます - レート制限はセッション単位だけでは不十分です。大量セッション攻撃に備え、グローバル単位との二層で設けましょう 🔧 実装方針 - ゲートウェイのポリシーをYAML等の宣言的定義で管理し、ツールごとにtype（read/write）・認可粒度・レート制限・サニタイズ・ログレベルを設定します - タスク種別・ユーザ権限・会話フェーズに応じてLLMに露出するツールを動的にスコーピングし、不要なツールを選択肢から除外します - ヘルスチェックと縮退モード（読取のみ許可）を設け、ゲートウェイ障害時にもシステム全体が停止しない設計にします - MCPサーバ間のスキーマ不統一をゲートウェイ層で正規化し、エージェントには一貫したインターフェースを提供します - 高リスクなコード実行はサンドボックスへルーティングし、長時間セッションには短命の権限リースで権限範囲を時間制限します #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # Model Router & Adaptive Effort｜モデル段階化と適応的努力配分 🎯 全リクエストを最高性能モデルで処理していませんか？ タスク難易度に応じてモデルを使い分けるだけで、品質を落とさずにコストを大幅に削減できます。実運用ではリクエストの60〜80%が軽量モデルで十分に処理できることが多いです。 🔥 解決する課題 すべてのリクエストを最高性能モデルで処理すると月間予算を容易に超過します。一方、すべてを軽量モデルに寄せると複雑な推論や計画タスクで品質が崩壊します。大型モデルはレイテンシも大きく、単純なタスクにまで使うとシステム全体の応答速度が不必要に悪化します。「コストか品質か」の二者択一に陥るのが問題です。 💡 提案パターン タスクの難易度・種別・リスクに応じて呼び出すモデルを動的に選択します。まず軽量モデルで試行し、信頼度が低ければ上位モデルへエスカレーションする構成です。ルーターはまずルールベース（入力長・タスク種別・キーワード）で始め、精度不足なら分類器を追加します。2〜3層（小型・中型・大型）が運用しやすい出発点です。 ✅ 選定条件 使うとき： - タスクの種類が多岐にわたり、定型処理と高度処理が混在している - 月間コスト上限が明確に存在する - トラフィックが十分にあり、ルーティング機構のコストを回収できる 使わないとき： - 全リクエストが同程度の難易度 → 単一モデルで十分 - 全件で品質を1%も落とせない → 常に最高性能モデルを使い、キャッシュでコスト削減 - リクエスト量が少なく（月数百件以下）、ルーティング開発コストが節約額を上回る ⚠️ 落とし穴 - ルーター自身のコストを無視しないでください。LLMをルーターに使うと、分類コストだけで軽量モデル1回分に匹敵する場合があります。まずルールベースで始めてください - 信頼度の定義を明確にしてください。構造化出力のパースエラー率・回答の拒否率・内部ログ確率など、測定可能な指標に落とし込まないと運用できません - エスカレーション無限ループを防いでください。最上位モデルでも信頼度が低い場合の打ち切り条件を設定し、人間エスカレーションまたはエラー返却にしてください 🔧 実装方針 - ルーターはまずルールベース（入力長・タスク種別・キーワード）で実装し、分類精度が不足した場合にのみメタ分類器へ昇格させます - モデル階層は2〜3層（小型・中型・大型）を共通インターフェースで抽象化し、プロバイダ差し替えを容易にします - 軽量モデルの応答に対して信頼度チェック（パースエラー率・拒否率・ログ確率）を行い、閾値未満なら上位モデルへ自動エスカレーションします - エスカレーションは最上位で打ち切り、それでも信頼度が低い場合は人間エスカレーションまたはエラー返却にします - ルーティング比率・コスト・レイテンシを定期的に監視し、モデルバージョン変更によるドリフトに備えて閾値を再調整する運用体制を整えます #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # Critic/Judge & Sampling-Aggregation｜独立検証と多数決 🎯 LLMの出力を、同じLLMに「正しい？」と聞いていませんか？ 生成と検証を別系統にするだけで、自己確認バイアスを断ち切り、出力の信頼性を構造的に高められます。 🔥 解決する課題 LLMは確率的に出力が揺れ、事実と異なる内容をもっともらしく生成します。生成と検証を同一のモデル・プロンプトに任せると、生成時のバイアスが検証にも引き継がれます。法律文書のドラフトを生成したLLMに「この文書は正しいか」と尋ねても、自分の生成物に肯定的に評価しがちです。これが「自己確認バイアス」です。 💡 提案パターン 2つの手法を組み合わせます。まず、生成系とは別のモデル・別のプロンプト・決定論的コードで出力を検証する「Critic/Judge」。次に、同じ入力からN個の候補を生成し、スコアリングや多数決で最良を選ぶ「Sampling-Aggregation」。両者を組み合わせると「N個生成 → Judgeが各候補を評価 → 最高スコアを採用」となります。コストはN倍になるため、リクエスト価値と失敗コストが高い経路に限定して適用します。 ✅ 選定条件 使うとき： - 誤った出力がそのまま下流に流れると実害がある（契約書・医療要約・金融レポートなど） - 1回の生成に追加コストをかける経済合理性がある - 出力品質を客観的に評価できる基準がある 使わないとき： - 多少の誤りが許容されるカジュアルな対話 → ガードレールで十分 - レイテンシが極めて厳しい（数百ミリ秒以内） - 評価基準が主観的で定量化困難（創作文章の「面白さ」など） ⚠️ 落とし穴 - JudgeがGeneratorと同じバイアスを持つ場合があります。同じモデル・同じ知識で評価すると同じ種類の誤りを見逃します。異なるモデルファミリを使うか、決定論的チェックをJudgeの一部に組み込んでください - Nを増やしてもコストは線形に増えますが、品質向上は逓減します。N=1とN=3の差は大きいですが、N=3とN=5の差は小さいことが多いです。まずN=3から始めてください - Judgeのプロンプトに評価基準を明示してください。「正しいか」だけでは曖昧な判断になります。事実性・論理的整合性・スキーマ適合など具体的な軸を与えてください 🔧 実装方針 - Generator（候補生成）とJudge（評価）を別々のモデルまたは別プロンプトで構成し、同一系統による自己確認バイアスを構造的に排除します - N個の候補生成は並列実行し、レイテンシの増加を最小限に抑えます - Judgeの出力はスコアと理由を含む構造化データとして定義し、集約ロジック（最高スコア選択・多数決）を決定論的コードで実装します - 全候補がJudgeの品質閾値を下回った場合のフォールバック（再生成上限・人間エスカレーション）を事前に設計しておきます - 決定論的チェック（スキーマ検証・値域チェック・データベース照合）をJudgeの一部として組み込み、LLM判定だけに頼らない検証層を構築します #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # Deadline & Budget Cascade｜期限・予算のカスケード伝播 🎯 エージェントが再帰的にサブタスクを生成して、気づけばコストが数十ドルに。「請求事故」を構造的に防ぐ方法があります。 全体の予算と期限を末端ノードまで伝播させれば、各ノードが自分で打ち切り判断できます。 🔥 解決する課題 エージェントの呼出ツリーが深くなると、各ノードは自分がどれだけのリソースを消費してよいか分かりません。高コストなLLM呼び出しが再帰的に積み重なり、請求事故が起きます。計画-反省の自己ループでは、改善の見込みが薄くても無限にリトライを繰り返しえます。根本原因は「全体の予算と期限がローカルな判断に伝わっていない」ことです。 💡 提案パターン Deadline & Budget Cascade（期限・予算のカスケード伝播）は、呼出ツリーのルートでdeadline（期限）とbudget（トークン・コスト・ステップ数の上限）を設定し、子タスクへ委譲するたびに残り枠を差し引いて伝播します。どの末端ノードでも「今の自分に残された時間・コスト」を知っており、枠を使い切る前に縮退・中断・部分結果返却に切り替えられます。deadlineは相対秒でなく絶対時刻で渡し、伝播時のズレを防ぎます。 ✅ 選定条件 使うとき： - エージェントがサブタスクを再帰的に生成、または複数ワーカーに並列委譲する - 1リクエストのコストが予測困難で、上限を置かないと請求事故が起きうる - タスク完了にSLAや期待値がある 使わないとき： - 呼出ツリーが1段で完結し、タイムアウトだけで十分な場合 - バッチジョブなど時間制約がなくコストも固定的な場合 ⚠️ 落とし穴 - deadlineは絶対時刻で渡すこと。相対秒を渡すと伝播のたびにズレが蓄積します（gRPCのgrpc-timeoutと同じ原則） - 子に全予算を渡さず、予備枠（10〜20%）を親に残すこと。子の結果を集約・フォーマットする時間とコストが必要です - 枯渇時の振る舞い（部分結果返却・人間エスカレーション・縮退モデル切替）を事前に決めておくこと。タイムアウト例外を投げるだけではUXが崩壊します 🔧 実装方針 - BudgetContextデータクラスにdeadline_at（絶対時刻）・max_cost_usd・max_steps・max_tokens・depth・max_depthを持たせ、呼出ツリーのルートで初期値を設定します - 子タスクへの委譲時にchild_budgetメソッドで残り枠からfractionを掛けて分配し、伝播マージン（概ね2秒）を差し引きます。予備枠としてルート予算の10〜20%を親に残します - 各ノードはis_exhaustedで残時間・残コスト・残ステップを確認し、枠を使い切る前に縮退・中断・部分結果返却に切り替えます - 並列子タスクではコストは各子の合算、deadlineは最も遅い子で決まることに注意し、分配比率は子タスクの重要度と予測コストで按分します - 予算消費率（consumed/limit比）をメトリクスとして観測し、閾値超過時にアラートを発火させる仕組みを組み込みます #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # Adaptive Timeout & Budget-Bounded Retry｜適応タイムアウト＋予算律速リトライ 🎯 リトライ3回で固定していませんか？LLMリトライ1回で数千トークン消費する世界では、回数でなく予算で律速すべきです。 固定タイムアウト・固定回数リトライは、エージェント時代のエラー処理には力不足です。 🔥 解決する課題 エージェント実行ではツール呼び出し（数秒）とLLM推論（数十秒〜分）でレイテンシ特性が全く異なります。同じタイムアウトで括ると、前者は待ちすぎ・後者は早すぎで切れます。さらに固定3回リトライでも、LLMリトライは1回あたり数千トークンを消費して予算を突き破りえます。429（レート制限）とスキーマ不適合を同じリトライで処理しても、後者は同じプロンプトでは直りません。 💡 提案パターン Adaptive Timeout & Budget-Bounded Retry（適応タイムアウト＋予算律速リトライ）は、操作クラス（ツール呼び出し・LLM推論・セッション全体）ごとにタイムアウトを分けます。リトライは固定回数でなく残りトークン予算で打ち切ります。エラーを一時障害・コンテンツ起因・コンテキスト長超過の3種に分類し、それぞれ指数バックオフ・self-correction・要約分割と対応戦略を切り替えます。予算を一定割合消費したら縮退（軽量モデルへのフォールバック）に移行し、尽きたらfail-fastで停止します。 ✅ 選定条件 使うとき： - LLM・ツール・外部APIなどレイテンシ特性の異なる操作を組み合わせている - リトライ1回あたりのコストが無視できない（LLM推論を含む） - ネットワーク一時障害とコンテンツ起因エラーの両方が発生しうる 使わないとき： - 単発LLM呼び出しのみで固定タイムアウトで十分な場合 - 非冪等な書込のみでリトライ自体が禁止される環境 ⚠️ 落とし穴 - 429応答のRetry-Afterヘッダを無視して自前バックオフだけで攻めると、プロバイダ側でさらに絞られます。必ずRetry-Afterを尊重してください - 非冪等書込のリトライには冪等キーが必須です。冪等キー無しのリトライは二重実行を招きます - self-correctionでエラー文をそのまま詰めすぎるとコンテキストが膨張してコンテキスト長超過に遷移します。エラー要約は200トークン以内に切り詰めましょう 🔧 実装方針 - タイムアウトを操作クラス別に定義します。ツール呼び出しは概ね10〜30秒、LLM推論は全体60〜120秒（ストリーミング時はトークン間5〜15秒）、セッション全体はdeadlineで律速します - エラーを3種に分類し、一時障害（429/5xx/timeout）は指数バックオフ＋ジッタで再送、コンテンツ起因（スキーマ不適合等）はエラー要約をコンテキストに追加してself-correction、コンテキスト長超過は要約・分割で対処します - リトライ上限は固定回数でなく残りトークン予算で判定します。一時障害は予算の90%まで、self-correctionは70%までを上限とします - プロバイダごとに独立したサーキットブレーカ（Closed/Open/Half-Open）を設置し、連続失敗が閾値に達したら遮断して縮退ラダー（軽量モデル→キャッシュ応答→静的フォールバック→fail-fast）を降ります - 全プロバイダが共通インターフェースを実装するプロバイダ抽象化層を設け、フォールバック先の切り替えを呼び出し元に対して透過的にします #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # Semantic Cache with No-Cache Zones｜禁止領域付きキャッシュ 🎯 「同じ質問に何度もお金を払っていませんか？」セマンティックキャッシュでコスト削減できますが、キャッシュしてはいけない領域を先に切らないと事故になります。 🔥 解決する課題 AIエージェントへのリクエストは1回あたりのコストが高く、同じ意図のクエリが繰り返し届く環境では無駄なトークン消費が積み上がります。しかし完全一致キャッシュでは表記揺れに対応できずヒット率が極端に低くなります。かといって意味的キャッシュを無差別に適用すると、個人情報依存の応答が他ユーザに返る、リアルタイムデータの古い情報を返す、安全判断の誤りが大量複製されるといった重大事故を招きます。 💡 提案パターン まず「キャッシュしてはいけない領域（No-Cache Zone）」をポリシーで先に定義します。PII依存・リアルタイムデータ・安全判断の3分類を禁止区域として切り出し、残りの安全な領域でのみベクトル埋め込みによる意味的類似度マッチングを行います。類似度閾値はリスクレベルに応じて段階的に設定し（低リスクFAQは0.92、中リスクは0.95、高リスクは0.97）、失敗コストが高い領域ほど厳しくします。キャッシュTTLには10-20%のジッタを加えて一斉失効による負荷集中（サンダリングハード）も防ぎます。 ✅ 選定条件 使うとき： - 同一・類似クエリの繰り返し率が全リクエストの概ね20%以上ある - 1リクエストあたりのLLMコストが無視できない - キャッシュ禁止領域を明確にポリシー定義できる 使わないとき： - ほぼ全クエリがユーザ固有コンテキストに依存し汎用キャッシュのヒットが見込めない - 全領域で失敗コストが極めて高くキャッシュ再利用が許容されない ⚠️ 落とし穴 - 埋め込みモデルを変更するとキャッシュ全体が無効化されます。モデルバージョンをメタデータに記録し、更新時の移行戦略を事前に決めておく必要があります - No-Cache Zoneのパターンマッチが甘いと禁止すべきクエリが漏れます。ルールベースだけでは表記揺れに弱いため、本番では意図分類器の併用を検討してください - 攻撃者が意図的に誤った応答をキャッシュに載せるキャッシュポイズニングのリスクがあります。書込時に品質スコアの閾値を設けてください 🔧 実装方針 - No-Cache Zoneの判定はルールベース（パターンマッチ＋メタデータ判定）を最小構成とし、本番では意図分類器を併用して表記揺れに対応します - 類似度検索の閾値はリスクレベル別に段階的に設定し、失敗コストが高い領域ほど閾値を引き上げます（低リスク0.92、中リスク0.95、高リスク0.97が出発点） - 中リスク領域ではキャッシュヒット時に軽量モデルで妥当性を再検証する二段構成を採用します - 埋め込みモデルのバージョンをキャッシュのメタデータに記録し、モデル更新時の段階的再埋め込みまたはフラッシュ戦略を事前に設計します - キャッシュTTLにジッタ（10-20%のランダム幅）を加え、一斉失効によるLLMへの負荷集中を防止します #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # プロンプトの成果物化 🎯 プロンプトの一文字を変えただけで本番障害。変更履歴もロールバック手段もありませんでした。 プロンプトはコードと同等以上のリスクを持つ成果物です。バージョン管理・テスト・段階デプロイの対象にしましょう。 🔥 解決する課題 LLMベースのシステムでは、プロンプトの些細な変更がモデル出力を大きく変えます。プロンプトをコード中のリテラル文字列として管理していると、変更追跡ができず障害の切り分けが困難になります。回帰テストの仕組みがなく品質変化を定量評価できません。問題が起きても「前のプロンプトに戻す」にコードデプロイが必要です。規制領域では「どのバージョンのプロンプトでどの判断がなされたか」の監査が求められますが、プロンプトがコード内に散在しているとこの紐づけが困難です。 💡 提案パターン プロンプトを独立した成果物としてバージョン管理し、変更時にはCIで回帰テスト（評価ハーネス）を実行します。本番環境ではカナリアリリース（5〜10%）で段階的にロールアウトし、品質低下を検知したら即座にロールバックします。実行時ログにはプロンプトIDとバージョンを記録し、事後監査で「この判断はどのプロンプトに基づくか」を示せる設計にします。プロンプトとモデルの互換性も記録し、モデル更新時に再評価が必要なプロンプトを特定できるようにします。 ✅ 選定条件 使うとき： - プロンプトの変更履歴と実行時バージョンの記録が求められる（規制領域・品質管理） - プロンプトが複数箇所から参照され、一元管理が必要 - A/Bテストや段階的ロールアウトを行いたい 使わないとき： - プロンプトが1〜2個で変更頻度も低い個人プロジェクトやPoC - 出力品質の変動が許容される探索的用途 ⚠️ 落とし穴 - テンプレート変数にユーザ入力が入る場合、インジェクション対策としてエスケープやサニタイズが必要です - プロンプト解決を外部APIに依存しすぎると可用性リスクが増します。起動時フェッチ＋ローカルキャッシュも検討しましょう - プロンプトは行指向フォーマット（YAML/Markdown）で保存してください。巨大な1行JSONではdiffレビューが困難です 🔧 実装方針 - プロンプトをYAML等の行指向フォーマットで管理し、テンプレート・変数定義・モデル互換性・評価ベースラインを一つのファイルに集約します - ランタイムではレジストリからプロンプトIDで解決し、カナリア対象なら確率的にカナリア版を返す仕組みを組み込みます - 実行時ログにプロンプトIDとバージョンを必ず記録し、事後監査で「どの判断がどのプロンプトに基づくか」を追跡可能にします - プロンプト変更時にはCIで評価ハーネスを自動実行し、品質の回帰を検知してからカナリアリリースで段階的にロールアウトします #AIエージェント# #ソフトウェアアーキテクチャ#