約 3 分で読めます

ETagでAIツールの上書き競合を防ぐIf-Match設計

AIエージェントが社内ドキュメントや顧客レコードを読み、数分後に修正版を書き戻す。この間に担当者が同じレコードを編集していたら、エージェントの更新は担当者の変更を黙って消します。読み取りから書き込みまでの時間が長いエージェントでは、人間の画面操作より起きやすい事故です。

HTTPには、この「更新の取りこぼし(lost update)」を防ぐ標準の仕組みがあります。ETagとIf-Matchです。本記事では、ツール実行の境界でこれをどう扱うかを整理します。重複実行の防止は冪等性の記事が主題で、ここでは扱いません。導入の伴走が必要な場合はAI運用の伴走支援もご覧ください。

ETagとIf-Matchは何を防ぐ仕組みか

ETagは取得時点のデータ版を示す識別子です。If-Matchで送り返すと、版が変わっていれば更新が拒否されます。

流れは3段階です。

  1. 読み取りのレスポンスから ETag ヘッダーを取得する
  2. 更新リクエストに If-Match: "取得したETag" を付ける
  3. サーバーが現在のETagと比較し、一致したときだけ更新を実行する

不一致のとき、サーバーは 412 Precondition Failed を返して更新を実行しません。Azure Blob Storageのドキュメントも同じ方式を楽観的並行性制御として説明しており、412を受けたらデータを再取得して内容を確認する流れを推奨しています。

ETagをツール実行まで保持するにはどうするか

読み取り結果にETagを含め、更新ツールの必須引数として受け渡します。値の保持をモデルの記憶に任せてはいけません。

エージェントの会話が長くなると、モデルが読み取り時の値を取り違えることがあります。ETagはモデルに生成させず、ハーネス側で保持するのが安全です。

  • 読み取りツールの返り値に etag フィールドを含める
  • 更新ツールのスキーマで if_match を必須引数にする
  • ツール実装は受け取った値をそのまま If-Match ヘッダーに載せる

更新ツールが if_match なしで呼べる設計だと、保護は最初の抜け道で無効になります。サーバー側で条件付きリクエストを強制したい場合、RFC 6585は 428 Precondition Required を定義しています。条件が無いリクエストを拒否し、「If-Matchを使うように」と案内するための状態コードです。

412を受けたらエージェントは何をすべきか

412は失敗ではなく「再確認の合図」です。無条件に再送せず、最新データを再取得して差分を確認してから更新し直します。

412を受けたツールが、新しいETagだけ取り直して同じ内容で再送する実装は避けてください。他者の変更を上書きする結果になり、If-Matchを付けた意味が消えます。

実装の流れは次のとおりです。

  1. 最新のデータとETagを再取得する
  2. 自分の変更と相手の変更が衝突しないか確認する
  3. 衝突しなければ、新しいETagで更新をやり直す
  4. 衝突する場合は人間に判断を戻す

再試行の回数には上限を設けてください。上限を超えたら、エージェントの判断で続行せず、担当者へのエスカレーションに切り替えます。

弱いETagとIf-Match未対応APIはどう扱うか

If-Matchは強い比較を使うため、W/で始まる弱いETagでは保護が成立しません。未対応APIには別の手段が要ります。

実装前に確認したい点は3つです。

  • 弱いETag: W/ 付きの値はIf-Matchの強い比較を満たせません。圧縮の仕組みがETagを弱い値に変えると、変更が無くても412になる場合があります
  • ワイルドカード: If-Match: * は「現在の表現が存在する」ことだけを条件にします。版の一致は確認しないため、競合防止には使えません
  • 未対応API: ETagを返さないAPIでは、更新日時やバージョン番号のフィールドで代用するか、更新の直前に再取得して比較します。完全な保護にはならないため、残るリスクは人間の承認で補います

規模別の留意点(SMB / エンタープライズ)

SMBでは、まず更新ツールに if_match を必須引数として足すだけで効果があります。大規模環境では、複数チームのツールが同じリソースを更新するため、428による強制をAPIゲートウェイ側に置き、全ツールに条件付き更新を義務づける運用が現実的です。

参考

まとめ

ETagの保持とIf-Matchの必須化で上書き事故は防げます。412は再確認へ戻し、無条件に再送しないことが要点です。

読み取り時のETagをツール境界で保持し、更新時にIf-Matchで送り返す。412は差分確認と人間への判断へつなぐ。この3点が設計の核です。AIツールの更新設計や運用体制の整備は、Kuu株式会社のAI運用伴走サービスにご相談ください。

関連記事

AGENTS.mdとは何か——複数ツールの指示を統一する標準A2A長時間タスク設計——ストリーミングとPush通知の使い分けMCPキャッシュ設計——ttlMsとcacheScopeの決め方A2A署名付きAgentCardの検証設計——JWSとJCS