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

> AIツールの更新が他者の変更を上書きしないよう、読み取り時のETagをIf-Matchで送り返す。412の扱いと428での必須化、弱いETagの落とし穴を整理する。

- Canonical: https://kuucorp.com/blog/agent-tool-http-etag-conditional-write/
- Date: 2026-11-11
- Last modified: 2026-11-11
- Publisher: Kuu株式会社 (https://kuucorp.com)

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

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

## 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ゲートウェイ側に置き、全ツールに条件付き更新を義務づける運用が現実的です。

## 参考

- [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html)
- [RFC 6585: Additional HTTP Status Codes](https://www.rfc-editor.org/rfc/rfc6585.html)
- [Manage concurrency in Blob Storage（Microsoft Learn）](https://learn.microsoft.com/en-us/azure/storage/blobs/concurrency-manage)

## まとめ

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

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