# AIエージェント開発の意思決定ポイント ## チェックポイント頻度 — エージェントの状態をどのくらいの間隔で永続化するか 🎯 ポイント LLMエージェントの処理が99%完了した時点でクラッシュ。チェックポイントがなければ、全部やり直しです。 でも毎ステップ保存すると、本来の処理よりI/Oの方が遅い。このバランス、どう取りますか？ 📋 概要 チェックポイント頻度は、エージェントの実行状態を外部ストアに永続化する間隔を制御するパラメータです。チェックポイントを取ることで、プロセスのクラッシュやプロバイダの障害が発生しても、最後に保存した地点から処理を再開できます。AIエージェントは1リクエストが数分〜数十分に及ぶことが珍しくなく、その間にLLMやAPIを何度も呼び出します。チェックポイントがなければ、クラッシュ時にトークン再消費とユーザーの待ち時間という二重の損失が発生します。一方で、チェックポイント取得にはI/Oコストが伴い、頻度が高すぎると本末転倒になります。 🔍 意思決定のポイント このダイヤルは主に **可逆性（reversibility）** で決めます。操作のやり直しが高コストなほど、チェックポイント頻度を上げます。 🔒 **必須のチェックポイント地点（可逆性にかかわらず常に取る）:** 1. 副作用を伴うツール実行の直前と直後 — 「この操作をやるべきか」の判断と「完了した」事実の両方を記録 2. 人間の承認ノードの前後 — 承認応答を失うのは致命的 3. コストの高いLLM呼び出しの後 — 大量トークンを消費した推論結果を保全 📐 **追加のチェックポイント地点（可逆性に応じて判断）:** - 各ツール実行の後 — 可逆性が低ければ全ツール後に、高ければ3回ごとなどに間引き - 各LLM応答の後 — 再生成コストが低ければ省略可能 - 計画の更新時 — エージェントが計画を修正した場合 💡 要点と詳細 📊 チェックポイントのタイミング目安: - ⭐ 副作用ツール実行の直前・直後: **必須** — 省略すると二重実行リスク - ⭐ 人間承認ノードの前後: **必須** — 承認応答を失うのは致命的 - 🔵 各LLM応答の後: 推奨 — 可逆性が低い場合は必須に格上げ - ⚪ 各読取ツール実行の後: 任意 — 再実行が安価なら間引いてよい - 🔵 一定時間経過ごと: 推奨 — 概ね30秒〜1分ごとの定期チェックポイント 状態の保存粒度も重要です。全メッセージ履歴をそのまま保存するのではなく、「再開に必要な最小集合」＋「本文はURIで外出し」という構成にすることで、I/Oサイズを抑えつつ再開可能性を確保します。 ⚖️ トレードオフ **頻度が低すぎる場合（作業が大量に失われる）:** - 10ステップ中9ステップ目のクラッシュで全やり直し。LLM呼び出し9回分のトークンコストが無駄に - 副作用ツール実行後にチェックポイントがないと、再開時に二重実行のリスク（メール再送など） - 人間の承認応答が失われ、ユーザーに再度承認を求めることになる **頻度が高すぎる場合（処理が遅くなる）:** - I/O待ちがボトルネックになり、30秒の処理が1分以上に - 大規模な状態の毎回書き込みでストレージコストとネットワーク帯域が浪費 - DBへの高頻度書き込みが他のクエリのレイテンシに影響 🛠️ ユースケース 🔍 **多段調査エージェント** — 10件のWebページを順次取得・分析してレポートを生成。各LLM分析完了後にチェックポイントを取り、8件目でクラッシュしても9件目から再開可能に。ページ再取得は安価なので間引いてもよいが、LLM分析（数千トークン消費）後は省略しないのが推奨です。 📝 **承認付きワークフロー** — 請求書生成→上長承認→メール送信。承認待ちの間はワーカーを解放し、チェックポイントの状態だけを維持。承認応答が来たら別のワーカーがチェックポイントから再開します。メール送信前には冪等キーも記録し、二重送信を防ぎます。 💬 **軽量チャット補助エージェント** — 可逆性が高くやり直しが容易なケース。チェックポイントは副作用操作（メッセージ投稿）の前後のみに絞り、LLM応答のチェックポイントは省略してレイテンシを優先します。 🔑 鉄則: 「副作用の直前で必ずチェックポイント」これだけ守れば最悪の事態（二重実行による不可逆な損害）を防げます。逆にこれを省略すると、他のチェックポイントをどれだけ取っていても安全性が崩壊します。再開時は冪等キーでツールを保護することもお忘れなく。 #AIエージェント# #ソフトウェアアーキテクチャ#