# AIエージェントをソフトウェアに組み込むプラクティス # Streaming with Progressive Commit｜進捗ストリーミング＋遅延コミット 🎯 トークンは即座に見せたい、でも副作用は検証してからコミットしたい。 「見せる」と「実行する」を分離すれば、体感レイテンシの短縮と副作用の安全性を両立できます。 🔥 解決する課題 エージェントの応答はレイテンシのばらつきが大きく、全トークン生成まで待たせると体感が悪化します。一方でツール呼び出しの副作用を生成途中で確定すると、ガードレール検証で棄却された際にロールバックが必要になります。「全部待ってから返す」か「生成と同時に確定する」かの二択では、体感か安全性のどちらかを犠牲にしてしまいます。 💡 提案パターン Streaming with Progressive Commit（進捗ストリーミング＋遅延コミット）は、生成中のトークンやツール実行結果をSSE/WebSocketでクライアントへストリーミングしつつ、副作用（外部API書き込み・DB更新など）は検証完了までコミットバッファに留めます。ストリーム上ではpreview（未確定）→ committed/rejected（確定/棄却）とイベントが遷移し、クライアントUIは中間状態を明示的に表示します。failure_costが高いほどバッファを深く取り、全ステップ完了後にまとめて確定します。 ✅ 選定条件 使うとき： - ユーザー向けUIがあり、first-token-timeの短縮が体験に直結する - エージェントがツール呼び出しで書き込み副作用を持ち、誤った副作用の取消しが困難 - 生成結果にガードレール検証やドライランを挟みたい 使わないとき： - 処理が常に数秒以内で、ストリーミングの恩恵がほぼ無い場合 - クライアントがSSE/WebSocketに対応できない場合 - 副作用が無い読取専用の質問応答（遅延コミットが不要） ⚠️ 落とし穴 - previewとcommitted/rejectedをクライアント側で区別しないと、未確定の結果を確定済みとして表示してしまいます。UIに「確認中」の中間状態を必ず設けてください - 長時間のマルチステップ実行ではコミットバッファが肥大化します。ステップ単位でチェックポイントを切り、確定済みバッファを解放しましょう - SSE接続が切れてもコミットバッファは残ります。再接続時の復元かタイムアウト破棄かのポリシーを事前に決めておく必要があります 🔧 実装方針 - LLMからのトークンはStream Buffer経由でSSE/WebSocketチャネルへ即座にプッシュし、ツール呼び出し結果はCommit Bufferに蓄積してpreviewイベントとしてクライアントに通知します - 全生成完了後にCommit Buffer内の各ツール呼び出しをガードレール検証し、パスすればcommittedイベント、棄却すればrejectedイベントをクライアントに送ります - ツール実行はまずドライランで結果をプレビューし、検証通過後に本コミットする二相構成を採ります - SSEイベント設計ではtoken・preview・committed・rejectedの各イベントタイプを明確に分離し、クライアントUIが中間状態（確認中）を適切に表示できるようにします - failure_costが高いワークフローではコミットバッファを深く取り、全ステップ完了後にまとめて確定します。低リスクの場合は単一ツール呼び出し単位で確定します #AIエージェント# #ソフトウェアアーキテクチャ#