# AIエージェントをソフトウェアに組み込むプラクティス # コンテキスト予算配分 🎯 「全部入れれば精度が上がる」は幻想です。コンテキストウィンドウは有限の予算として管理しましょう。 スロットごとに配分比率を決め、信号密度を最大化するパターンです。 🔥 解決する課題 RAGやメモリを使うエージェントでは、検索結果・会話履歴・システム指示・長期メモリが同じコンテキストウィンドウを奪い合います。情報を詰め込むほどコストは増え、会話が長くなるとシステム指示の割合が縮んで振る舞いが劣化します。さらに"Lost in the Middle"問題により、窓の中盤に置かれた重要な情報が実質的に無視されてしまいます。 💡 提案パターン コンテキストウィンドウをシステム指示・検索結果・会話履歴・メモリなどのスロットに分け、各スロットに最大占有率と優先度を設定します。システム指示は圧縮対象外の固定枠（10〜20%）として先に確保し、検索結果はリランク後にtop-k件に絞り、履歴は窓使用率が閾値を超えたら要約圧縮します。配置順序はLost in the Middle対策として、最重要情報を先頭に、直近入力を末尾に置きます。cost_sensitivityが高い環境ほどtop-kを絞り、圧縮閾値を下げ、履歴を短く保ちます。 ✅ 選定条件 使うとき： - RAGやメモリを使い、投入候補がモデル窓サイズの50%を超えうる - コスト感度が中以上で、投入トークンの増加がコストや推論時間に影響する - 複数ターンの会話で履歴が蓄積し、他の情報のスペースを圧迫する 使わないとき： - 投入情報がシステム指示＋単発入力のみで窓の30%未満に収まる場合 - ロングコンテキストモデルを使い投入量が窓の20%未満、かつコスト感度が低い場合 ⚠️ 落とし穴 - システム指示を圧縮対象にしてはいけません。ツール定義や安全指示が削られると振る舞いが壊れます - リランクなしのtop-kは信号密度が低いです。ベクトル検索上位20件からクロスエンコーダで3〜8件に絞りましょう - 要約圧縮は非可逆です。重要な決定事項や固有名詞が落ちるリスクがあるため、キーワード抽出を併用してください 🔧 実装方針 - コンテキストウィンドウをスロット（system/user/retrieval/history/memory）に分割し、各スロットに最大占有率・優先度・圧縮可否を定義した構造体で管理します - システム指示は圧縮対象外の最高優先度として先に確保し、残りの予算を他スロットに優先度降順で配分します - 検索結果はベクトル検索の上位候補をクロスエンコーダでリランクしてから予算内に収め、信号密度を最大化します - 履歴スロットが予算を超過した場合は要約圧縮を適用し、圧縮前にキーワード抽出して重要情報の欠落を防ぎます #AIエージェント# #ソフトウェアアーキテクチャ#

AI関連のポストでフォロワーふえたうれし！となってよくよく見たら例のAI生成のBOTだった…。かなしみのブロック😢　彼らは紫陽花が好きなようで…

# AIエージェントをソフトウェアに組み込むプラクティス # 階層化メモリ 🎯 「全部コンテキストに詰め込む」設計は、ウィンドウ溢れとハルシネーションの永続化を同時に引き起こします。 メモリを3層に分けるだけで、コンテキスト効率と記憶の信頼性を両立できます。 🔥 解決する課題 エージェントが複数ターンに跨がるタスクを扱うとき、すべての情報をコンテキストウィンドウに詰め込む「フラット記憶」では2つの問題が同時に起きます。会話履歴・ユーザ属性・中間結果・外部知識が混在するとウィンドウが溢れ、古い情報から押し出されて文脈が断絶します。さらにLLMが生成した推測をそのまま永続化すると、ハルシネーションが長期記憶に定着し、以降のセッションを汚染し続けます。 💡 提案パターン メモリを作業記憶（ターン内の中間状態）・短期記憶（セッションストア、TTL付き）・長期記憶（ベクトルDB/KVS）の3層に分離します。作業記憶は自由に読み書きし、コンテキストリセットで消えます。短期記憶には信頼度タグを付与し、ユーザ発話由来は高信頼、LLM推測由来は低信頼とマークします。長期記憶への昇格には反復確認やユーザ承認を要求し、ハルシネーションの永続化を防ぎます。failure_costが高い領域ほど昇格閾値を厳しくし、TTLを長めにとって安全側に寄せます。 ✅ 選定条件 使うとき： - 複数セッションにわたって情報を引き継ぐ必要がある - 中間結果の量がコンテキストウィンドウの30%を超える見込みがある - 確定事実と推測の区別が必要で、誤った記憶の波及影響が大きい 使わないとき： - 1ショットで完結しセッション間の引継ぎが不要な場合 - コンテキストウィンドウに全情報が収まる場合 - メモリの書込制御だけが課題で、階層分離自体は不要な場合 ⚠️ 落とし穴 - 作業記憶と短期記憶の境界が曖昧になりがちです。外部ストアへの書込を境界線にし、LLMの内部状態に頼らないでください - 長期記憶のエントリ数が増えると無関係な記憶がコンテキストに混入し、ハルシネーションの原因になります - マルチエージェント構成で各Workerが直接長期記憶に書き込むと整合性が崩れます。長期記憶はSupervisorが一元管理しましょう 🔧 実装方針 - 作業記憶（dict/インメモリ）・短期記憶（Redis等TTL付きセッションストア）・長期記憶（ベクトルDB）の3層を明確に分離し、外部ストアへの書込を境界線とします - recall時はコンテキスト予算内で3層から関連情報を想起し、関連度と信頼度でランク付けして注入量を制御します - 短期→長期への昇格には信頼度スコアの閾値チェックと承認状態の検査を設け、未検証情報の永続化を防ぎます - 記憶種別ごとにTTLを設計し（リアルタイムデータは分単位、ユーザ嗜好は週単位、不変属性は無期限）、failure_costが高いほど短めに設定します #AIエージェント# #ソフトウェアアーキテクチャ#

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

AIエージェントをエンタープライズシステムに組み込むプラクティス 【MCPゲートウェイ / ツール・フェデレーション（MCP Gateway）】 💡 ポイント 「エージェント5つ × SaaS 10種 = 50本の個別統合。この掛け算地獄を解消するのがMCPゲートウェイです。」 エージェントが増え、接続先SaaSが増えるたびに統合コストが爆発します。ツール定義の乱立、スキーマの不整合、そしてSaaSのサイレント仕様変更による暗黙の破綻。これらをアーキテクチャレベルで解決します。 🔥 解決する課題 - N（エージェント）×M（SaaS）の統合コスト爆発 - 各エージェントが独自にツール定義を持つことによる重複・不整合 - ツール経由の間接プロンプトインジェクション - エージェントに見えるツールが多すぎることによる選択精度の劣化 - SaaSのサイレント仕様変更（APIレスポンス形式変更等）による暗黙の破綻 🏗️ 提案パターン 各SaaSコネクタをMCP（Model Context Protocol）サーバとして束ね、ゲートウェイがツールの発見・認可・呼び出し監査・スコープ制御を一元管理します。ツール許可リストを主体（部署×エージェント種別）で動的に絞り、エージェントに見えるツールを必要最小限にします。危険ツール（削除・送金・外部送信など不可逆操作）には承認フックを設置します。さらに、ツール定義/APIスキーマを「契約」としてバージョン管理し、定期的に実APIと突合してドリフト（乖離）を検知します。後方互換のないドリフトを検出した場合は、アラート＋該当ツールの一時無効化で安全側に倒します。 ✅ 選定条件 - 採用する場合：連携SaaSが10種以上。複数エージェントが共通ツールを使う。N×M統合の複雑さに困っている。 - 採用しない場合：ツールが2〜3個固定の単機能エージェント（直結のほうが堅牢でシンプル）。依存APIが安定していて変更頻度が極めて低い環境。 ⚠️ 落とし穴 - エージェントに露出するツールが20〜30を超えると選択精度が低下します。tool RAGで意図に応じて動的に絞るか、役割別サブエージェントに分割してください。 - 契約テスト（ドリフト検知）を導入しないと、SaaS側の仕様変更に気づかず、エージェントが誤ったデータを処理し続けます。Salesforce APIのフィールド変更などは実際に起きる頻度が高いです。 - MCPサーバの認可設計を後回しにすると、全エージェントが全ツールにアクセスできる状態が放置されます。 🛠️ 実装方針 - 各SaaS（Salesforce / ServiceNow / Jira / Slack / Box 等）のMCPサーバを構築します。公式MCPサーバがあればそれを採用し、なければOpenAPI定義からツールを自動生成して自作MCPサーバとして用意します。 - MCPゲートウェイを配置し、ツールレジストリ（カタログ）を構築します。各MCPサーバが提供するツールを一覧化し、部署×エージェント種別でアクセス可能なツールを動的にフィルタリングする許可リストを設定します。 - OAuth 2.1 ベースの認可と承認フックを設定します。不可逆操作（削除・送金・外部送信）を行うツールにはP09（動的認可PDP）と連携した承認ゲートを設置し、人間の承認なしに実行されない構成にします。 - 契約テスト（Pact等）とスキーマレジストリでドリフト検知パイプラインを構築します。週次でツール定義と実APIスキーマを突合し、後方互換のない変更を検出した場合はアラート＋該当ツールの自動無効化を行います。 - tool RAG または役割別サブエージェント分割で、各エージェントに露出するツール数を20以下に制御します。意図に応じて動的にツールを絞り込み、選択精度を維持します。 #AIエージェント# #エンタープライズアーキテクチャ#