# 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エージェント# #ソフトウェアアーキテクチャ#