Idempotency

あるツール関数自体が冪等でない場合（外部APIを呼び出して注文するなど）、Agentはこの外部APIを変更せずに、自分のリトライロジックを依然として安全にするにはどうすればいいですか？

外部API自体が冪等キーのサポートを提供していない場合（呼び出すサードパーティサービスの注文エンドポイントが「呼び出すたびに新しい注文が生成される」よう設計されており、識別子を渡して重複を回避させてくれない）、相手のAPIの動作を変更することはできませんが、Agent自身のアーキテクチャ層に追加の保護層を加えることができます。一般的な方法は2つあります。

方法1：外部APIを呼び出す前に、自分のシステムでリクエストの重複排除を行う。具体的には、Agentが注文操作を開始する準備をするたびに、まず自分のデータベースに「今回の操作の一意識別子」と「操作内容のハッシュ値」を記録し、実際に外部APIを呼び出す前に、内容が完全に同一で最近すでに処理された記録があるか確認します——あれば、これは重複トリガーの可能性があり（前述のリトライ戦略記事で触れた、ある段階の誤判定により同じタスクが2回トリガーされる状況など）、この呼び出しを直接スキップし重複注文しません。なければ実際に外部APIを呼び出し、この呼び出しを記録します。この方法の本質は、「冪等でない外部API」の前に自分が制御する冪等層を加え、冪等性の責任を外部APIから自分のシステムに移すことです。

方法2：リトライのタイミングと範囲を制限し、「前回の呼び出しが確実に失敗した」と確定できる場合にのみリトライする。Agentが非冪等操作を誤ってリトライしてしまう多くの状況の根源は「前回の呼び出しが本当に成功したかどうか分からない」ことです（ネットワークタイムアウトでは、リクエストが届かなかったのか、届いたがレスポンスが返ってこなかったのか分かりません）。「前回の呼び出しが確実に失敗し、相手システムが全く処理していない」と明確に判断できる場合にのみリトライする（タイムアウトのような曖昧な状況ではなく、明確なエラーレスポンスコードを受け取った場合など）ことで、誤って重複注文をトリガーする確率を大幅に下げられますが、この方法は完璧ではありません。「ネットワークタイムアウト」のような曖昧な状況はそもそも100%排除できないためで、これが方法1（自分で制御する冪等層）が通常より信頼性が高く優先的に採用すべき理由です。

実務上の推奨：この操作が実際の金銭や不可逆的な結果に関わる場合、追加のエンジニアリング投資が必要でも方法1（自前の冪等層構築）を優先すべきです。方法2は補助的な手段として重ねて使用できますが、唯一の防御線であるべきではありません。ネットワーク環境の不確実性はそもそも完全には排除できないためです。

冪等キー（idempotency key）を設計する際、この識別子はAgentが生成すべきか、それともリクエストを発起するユーザーが生成すべきか？2つの方法にどんな違いがありますか？

この2つの方法はそれぞれ異なるシナリオに適しており、核心的な違いは「論理的に同一の操作について、重複判定の範囲がどれだけ広くあるべきか」にあります。

Agent自身が冪等キーを生成する：「Agentが自律的にリトライを決定する」シナリオに適しています——例えばAgentが前回の呼び出しがネットワークタイムアウトで失敗したと判断しリトライを決定する場合、この時Agentは「この同じ操作」に元々生成された識別子を引き継ぐべきで、リトライのたびに新しい識別子を生成すべきではありません（リトライのたびに新しい識別子を使うと、冪等キーメカニズムは完全に意味を失います。バックエンドがすべてのリトライを全く新しい未処理の操作として扱ってしまうためです）。このシナリオでは、識別子の生成タイミングは「この操作が最初に提起された時」で、その後何回リトライしても同じ識別子を引き継ぎます。

ユーザー（またはユーザー側のアプリケーション）が冪等キーを生成する：「同じユーザーの意図が、異なる経路を通じて複数回トリガーされる可能性がある」シナリオに適しています——ユーザーがアプリケーションインターフェースで「実行」ボタンをクリックし、ネットワーク遅延のため成功して送信されたか確信が持てず、もう一度クリックしたとします。この場合、冪等キーがユーザー側（アプリケーションインターフェース）で生成されこの「ユーザーの意図」に付随していれば、この2回のクリックが背後で2回の独立したAgent呼び出しをトリガーしても、両方の呼び出しが同じユーザー側生成の識別子を持っている限り、バックエンドは依然としてこれが同じ意図であると正しく判断し、1回だけ実行できます。

両者の本質的な違い：Agent自身が生成する冪等キーは「Agent内部のリトライロジック」という層の重複を保護します。ユーザー側で生成される冪等キーは、より上位でより広い範囲をカバーする「ユーザーの意図」の重複を保護し、ユーザー自身の不注意な重複操作もAgent内部のリトライも含みます（ユーザー側で生成された識別子は理論上、Agent内部で何回リトライされても処理チェーン全体を貫いて引き継がれるため）。

実務上の推奨：システムアーキテクチャにおいて、ユーザーの意図が明確なインターフェース操作（ボタンのクリックなど）を通じてトリガーされる場合、識別子をユーザー側で生成することを優先すべきです。これにより「ユーザーの重複操作」と「Agent内部のリトライ」の両方の重複源を同時にカバーでき、保護範囲がより完全になります。プロセス全体が完全にAgent自律でトリガーされ、ユーザーのリアルタイム操作の段階がない場合（前述の自動化収益最適化Agentなど、タスクはAgent自身の判断でトリガーされる）、Agentがタスク生成時点で自分で識別子を生成すれば十分で、ユーザー側の識別子生成ロジックを追加設計する必要はありません。

Agentシステムが再起動またはクラッシュした場合、以前記録された冪等キー情報が永続化保存されていなければ、再起動後保護機能が失われますか？この抜け穴を防ぐにはどう設計すべきですか？

これは実際に存在するリスクです。冪等キーの記録がメモリにしか存在しない場合（プログラム実行時の変数にすぎず、データベースや他の永続的ストレージに書き込まれていない）、Agentシステムが再起動またはクラッシュすると、これらの記録はすべて失われます。再起動後、「実はクラッシュ前にすでに処理済み」の重複リクエストを受け取った場合、システムは全く新しいリクエストと誤判定し重複実行してしまいます——これはまさに冪等キーメカニズムが本来防ぐべきシナリオであり、冪等キーの記録自体が十分に信頼できなければ、保護メカニズムは形骸化します。

正しい設計原則：冪等キーの記録自体は永続的ストレージに書き込まれるべきで、メモリにのみ存在すべきではない。具体的には、各操作が実行準備される前に、まず「今回の操作の識別子」と「これから実行される操作内容」を同期的にデータベースに書き込みます（操作が完了してから記録するのではなく、これは重要な点で理由は後述します）。操作完了後、「実行結果」もこのレコードに更新します。これにより、システムが操作実行中に突然クラッシュしても、再起動後少なくとも「この識別子の操作は以前に実行が開始されたが完了したかは不明」という状態を照会でき、全く記録がないという状態を避けられます。

なぜ「実行前」に記録を書き込むべきで「実行後」ではないのか：操作完了後に冪等キー記録を書き込むことを選んだ場合、時間窓のリスクがあります——「操作が実際に実行完了した」時点と「この実行の記録がデータベースに書き込まれる」時点の間でAgentがクラッシュすると、再起動後データベースにこの操作の記録が全くありません（記録がまだ書き込まれていなかったため）。Agentは「この操作はまだ実行されていない」と誤判定し、再度実行してしまい、前述の重複請求のような問題を引き起こします。逆に、「これから実行する」記録を先に書き込んでから実際に操作を実行すれば、途中でクラッシュしても少なくともデータベースには「この操作がかつてトリガーされた」という記録があり、再起動後まず「この操作が外部システム（オンチェーンまたはサードパーティAPI）で実は実行に成功していたか」を確認してから次のステップを決められ、全く手がかりのないまま再実行することを避けられます。

追加の実務的な考慮：冪等キーの記録は無期限に保持できません（そうしないとストレージ容量が増え続ける）。通常、合理的な保持期限を設計する必要があります（24時間または7日間など、ビジネスロジック上合理的なリトライ窓がどれくらいの長さかによる）。この期限を超えた古い記録はクリーンアップでき、この時間を超えると重複リクエストの確率は極めて低く、保持し続ける限界価値は低いためです。

マルチAgentシステムで、Sub-agent Aがすでに冪等キーを使ってある操作を成功実行したが、Handoffプロセス中の情報損失により、Sub-agent Bが同じ論理操作に対して再度リクエストを発起した場合、この跨Agentの重複を冪等キーメカニズムはまだ保護できますか？

保護できますが、前提として「冪等キー自体がタスクと一緒に引き継がれる」必要があり、Sub-agent A内部にのみ存在するのではいけません。これは前述のHandoff項目で繰り返し強調された「引き継ぎパッケージには十分なメタ情報を含めるべき」という原則と呼応します。

跨Agent冪等性保護の重要な設計：冪等キーはSub-agent Aの内部実装の詳細として扱われるべきではなく、「この論理操作」自体のプロパティとして扱われるべきで、タスクの最初から付与され、Handoffパッケージとともに完全にSub-agent Bに伝達されるべきです。具体的には、タスク自体が最初（Orchestratorが割り当てる時など）にすでに一意のタスク識別子を生成していれば、この識別子はタスクのライフサイクル全体を貫くべきで、途中で何回Handoffが発生し何人の異なるSub-agentに処理されても、同じ論理操作は同じ識別子を引き継ぐべきです。

Handoffプロセスが本当にこの識別子を失った場合何が起こるか：あなたの質問で述べられたシナリオのように、Sub-agent Bは元の識別子を受け取っていないため、自分で新しい識別子を生成してリクエストを発起するしかありません。バックエンド（実際に送金を実行する責任を持つシステムなど）から見れば、これは全く新しい識別子を持つリクエストであり、冪等キーメカニズムはこれを「未処理の新しい操作」と判断し正常に実行してしまい、重複実行の問題を引き起こします——これは冪等キーメカニズム自体が失敗したのではなく、失敗したのは「Handoffプロセス中の識別子の伝達の完全性」であることを意味します。問題は上流（Handoff情報の損失）にあり、下流（冪等キーメカニズム自体）にはありません。

このシナリオをどう防ぐか：前述のリトライ戦略記事で触れた「引き継ぎパッケージの完全性テスト」のようなテストフレームワークがカバーすべき内容に加え、Handoffメカニズムとは独立した追加の保護層を加えられます——実際に操作を実行する前に、「この識別子が処理済みか」だけでなく、「この操作の具体的な内容（送金の対象アドレス・金額）が、最近処理済みのある操作と高度に類似しているか」も追加でチェックします。識別子が異なっていても、操作内容がほぼ一致しタイミングが近ければ、無条件に受け入れて直接実行するのではなく、追加の確認フロー（人的介入による確認、または少なくともアラートの記録）をトリガーすべきです。この内容レベルの類似度チェックは、識別子メカニズムの補完的な防御線として機能し、識別子自体が何らかの理由（Handoff情報の損失）で失敗した場合でも保護層を提供できます。

核心原則：マルチAgentシステムの冪等性保護は単一のSub-agent内部だけで設計してはならず、タスクのライフサイクル全体を貫き、すべてのHandoffステップをまたぐ一貫性の要件として扱わなければなりません。これは前述のHandoff項目の「引き継ぎパッケージの完全性」原則を冪等性という具体的なシナリオに拡張した必然的な結果です——単一のステップでどれほど厳密に設計されたメカニズムでも、マルチAgent連携時の情報伝達の完全性を考慮していなければ、連携の隙間で失敗する可能性があります。