チェックポイント頻度

このダイヤルは何か

チェックポイント頻度は、エージェントの実行状態を外部ストアに永続化する間隔を制御するダイヤルです。チェックポイントを取ることで、プロセスのクラッシュやプロバイダの障害が発生しても、最後に保存した地点から処理を再開できます。

AIエージェントシステムでは、1リクエストが長く（F1）、数分から数十分に及ぶ処理が珍しくありません。その間にプロバイダ可用性が不安定（F7）な外部LLMやAPIを何度も呼び出します。チェックポイントが無ければ、処理の99%が完了した時点でクラッシュしても最初からやり直しになります。これはコスト（トークン再消費）の面でもUX（ユーザーの待ち時間）の面でも大きな損失です。

一方で、チェックポイントの取得にはI/Oコスト（データベースやオブジェクトストレージへの書き込み）が伴います。1ステップごとに全状態を永続化すると、本来の処理よりもチェックポイント書き込みの方に時間を取られるという本末転倒な状況に陥りかねません。適切な粒度のバランスを見つけることがこのダイヤルの本質です。

効かなすぎる害 ⇔ 効きすぎる害

効かなすぎる害（チェックポイント頻度が低すぎる）

チェックポイントを取る頻度が低いと、クラッシュ時に大量の作業が失われます。

• 10ステップの処理でチェックポイントが先頭にしかない場合、9ステップ目のクラッシュで全ステップをやり直しになります。LLM呼び出し9回分のトークンコストが無駄になります
• 副作用を伴うツール呼び出しの後にチェックポイントが無いと、再開時にどこまで実行済みか分からず、二重実行のリスクが高まります。たとえばメール送信の成功後にチェックポイントを取らずにクラッシュすると、再開時にメールを再送してしまう可能性があります
• 人間の承認応答が失われます。ユーザーが承認した後にチェックポイントが無ければ、クラッシュ後に再度承認を求めることになり、ユーザー体験が著しく悪化します

効きすぎる害（チェックポイント頻度が高すぎる）

チェックポイントを取りすぎると、処理のスループットが低下します。

• 全トークン生成のたびにチェックポイントを取ると、I/O待ちがボトルネックになり、本来30秒で終わる処理が1分以上かかります
• 大規模な状態（数MBのコンテキスト全文）を毎回書き込むと、ストレージコストとネットワーク帯域が浪費されます
• データベースへの高頻度書き込みが他のクエリのレイテンシに影響を及ぼし、システム全体のパフォーマンスが劣化します

決め方

このダイヤルは主に [reversibility] で決めます。操作の可逆性が低い（やり直しが高コスト）ほど、チェックポイントの頻度を上げます。

必須のチェックポイント地点

以下のタイミングでは、[reversibility] の値にかかわらず必ずチェックポイントを取ります。

1. 副作用を伴うツール実行の直前と直後 — 実行前に取ることで「この操作をやるべきかどうか」の判断を再開時に再利用でき、実行後に取ることで「この操作は完了した」という事実を記録します
2. 人間の承認ノードの前後 — 承認要求の前に取ることで承認待ちの状態を保持し、承認応答の後に取ることで承認結果を保全します
3. コストの高いLLM呼び出しの後 — 大量のトークンを消費した推論結果を失わないようにします

追加のチェックポイント地点

以下のタイミングでは、[reversibility] に応じてチェックポイントの取得を判断します。

• 各ツール実行の後 — [reversibility] が低い場合は全ツール実行後に取り、高い場合は一定間隔（例：3ツール実行ごと）でまとめて取ります
• 各LLM応答の後 — 推論結果を保全します。[reversibility] が高く、再生成のコストが低い場合は間引いても構いません
• 計画の更新時 — エージェントが計画を修正した場合、新しい計画を永続化します

状態の保存粒度

チェックポイントに何を保存するかも重要です。全メッセージ履歴をそのまま保存するのではなく、「再開に必要な最小集合」＋「本文はURIで外出し」という構成にすることで、I/Oサイズを抑えつつ再開可能性を確保します。

目安値（出発点）

チェックポイントのタイミング	推奨度	条件
副作用ツール実行の直前・直後	必須	常に取る。省略すると二重実行リスク
人間承認ノードの前後	必須	承認応答を失うのは致命的
各LLM応答の後	推奨	[reversibility] が低い場合は必須
各読取ツール実行の後	任意	再実行が安価なら間引いてよい
一定時間経過ごと	推奨	概ね30秒〜1分ごとの定期チェックポイント

[reversibility] が低い環境（金融・医療・本番環境操作）では全ステップでチェックポイントを取ることを推奨します。[reversibility] が高い環境（開発補助・リサーチなど）では、副作用ツールの前後と承認ノードの前後だけに絞っても許容できるでしょう。

具体的なシナリオ

シナリオ1：多段ツール呼び出しを行う調査エージェント

10件のWebページを順次取得し、各ページの内容をLLMで分析し、最終レポートを生成するエージェントです。

推奨するチェックポイント戦略：

• 各Webページ取得後にチェックポイント（取得結果を保存）
• 各LLM分析の完了後にチェックポイント（分析結果を保存）
• 8件目の分析後にクラッシュした場合、チェックポイントから再開し、9件目から処理を続行できます

[reversibility] が高い（ページ再取得は安価）ため、Webページ取得後のチェックポイントは間引いてもよいでしょう。ただしLLM分析はコストが高い（数千トークン消費）ため、各分析後のチェックポイントは省略しないことを推奨します。

シナリオ2：承認を含むワークフロー

エージェントが請求書を生成し、上長の承認を得てからメールで送信するワークフローです。

推奨するチェックポイント戦略：

• 請求書生成後にチェックポイント（生成した請求書の内容を保存）
• 承認要求送信前にチェックポイント（「これから承認を求める」状態を記録）
• 承認応答受信後にチェックポイント（「承認済み」状態を記録）
• メール送信前にチェックポイント（「これから送信する」状態を記録、冪等キーも記録）
• メール送信後にチェックポイント（「送信完了」状態を記録）

承認待ちの間（数分〜数時間）はワーカーを解放し、チェックポイントの状態だけを維持します。承認応答が来たら、別のワーカーがチェックポイントから再開します。

シナリオ3：コスト重視の軽量エージェント

社内チャットの補助を行う軽量エージェントで、[reversibility] が高く（やり直しが容易）、[failure_cost] が低いケースです。

推奨するチェックポイント戦略：

• チェックポイントは最小限に抑えます
• 副作用を伴う操作（メッセージ投稿）の前後のみチェックポイント
• LLM応答のチェックポイントは省略（再生成のコストが低いため）

このシナリオではチェックポイントのI/Oコストを削減し、レイテンシを優先します。

実践的なアドバイス

• 「副作用の直前で必ずチェックポイント」は鉄則です。この1点だけ守れば、最悪の事態（二重実行による不可逆な損害）を防げます。逆にこれを省略すると、どれだけ他のチェックポイントを取っていても安全性が崩壊します。

• チェックポイントの書き込みはLLM呼び出し中のトランザクション内で行わないでください。F1 短トランザクション長セッションの原則に従い、チェックポイント書き込みは短い独立したトランザクションで行います。LLM呼び出し中にDBトランザクションを開いたままにすると、ロック保持時間が数十秒〜数分に及び、他のクエリをブロックします。

• 再開時は副作用ツールを冪等キーで保護してください。チェックポイントからの再開では、直前のツール呼び出しが「完了したがチェックポイント書き込み前にクラッシュした」のか「未実行のままクラッシュした」のか判別が困難です。C4 冪等コマンド包装があれば、完了済みの操作は自動的にスキップされます。

• 承認待ちの間はワーカーを解放してください。チェックポイントを取った上で承認待ち状態に入り、ワーカースレッドやプロセスは解放します。承認応答が来たら、別のワーカーがチェックポイントから再開する設計にします（A2 耐久非同期セッション）。

• チェックポイントのサイズを監視してください。処理が進むにつれてメッセージ履歴が膨張し、チェックポイントのサイズが増大します。閾値（例：1MB）を超えたら、古いメッセージを要約してサイズを圧縮する仕組みを導入します。

関連パターン

• A2 耐久非同期セッション — チェックポイント機構の中核パターンです。状態の外部化、再開メカニズム、イベントソーシングとの連携を詳述しています。
• C4 冪等コマンド包装 — チェックポイントからの再開時に副作用の二重実行を防ぐ仕組みです。チェックポイントと常にセットで使います。
• E1 リスクベース人間承認 — 承認ノードの前後でのチェックポイント取得が特に重要になるパターンです。
• G1 二層観測 — チェックポイントデータの保持期間を「ホット/コールド」二層で管理し、ストレージコストと監査要件のバランスを取ります。
• F1 短トランザクション長セッション — チェックポイント書き込みのトランザクション設計の基盤です。