LLM Tool Call 冪等性設計（Idempotency for AI Agent Tools）

f(x) = f(f(x)) = f(f(f(x)))

┌──────────┐   ①使用者狂點送出   ┌──────────────┐
│ Frontend │ ──────────────────▶ │ AI           │
└──────────┘                     │ Orchestrator │
                                 └──────┬───────┘
                    ②Orchestrator       │  ③LLM 幻覺 / 重複 tool_call
                      網路超時重試       │     (同一輪吐兩次相同請求)
                                        ▼
                                 ┌──────────────┐
                                 │  Tool / API  │  ← 副作用發生處
                                 └──────────────┘

# python
# IDEA: Check-Act-Record —— 先查快取，沒命中才執行，執行完寫回快取
async def request_refund(order_id: str, amount: float, idempotency_key: str):
    # 1. 查詢 idempotency_key 是否已執行過
    cached = await redis.get(f"idem:{idempotency_key}")
    if cached:
        return json.loads(cached)  # 回傳上次結果，不重複執行

    # 2. 執行退款
    result = await payment_api.refund(order_id, amount)

    # 3. 儲存結果，TTL 24 小時（覆蓋 LLM 可能重試的時間窗）
    await redis.setex(f"idem:{idempotency_key}", 86400, json.dumps(result))
    return result

# python
# Anthropic Messages API：從 tool_use block 取出原生 id
for block in response.content:
    if block.type == "tool_use":
        idem_key = f"idem:{block.id}"          # e.g. idem:toolu_01A09q90qw
        result = await dispatch(block.name, block.input, idem_key)

# python
import hashlib, json

def payload_key(session_id: str, tool_name: str, kwargs: dict) -> str:
    # sort_keys 確保 dict 順序不影響 hash；剔除易變欄位
    volatile = {"timestamp", "request_time", "nonce", "trace_id"}
    stable = {k: v for k, v in kwargs.items() if k not in volatile}
    digest = hashlib.sha256(
        json.dumps(stable, sort_keys=True, ensure_ascii=False).encode()
    ).hexdigest()[:16]
    return f"idem:{session_id}:{tool_name}:{digest}"

第一層（廣義去重）：原生 tool_call_id  → 擋掉 Orchestrator 網路重試
第二層（業務兜底）：refund:{order_id}   → 擋掉「LLM 重新生成」造成的新 tool_call_id

# python
# IDEA: Two-Phase Lock —— 成功才寫冪等快取，失敗釋放鎖允許重試
async def request_refund(order_id: str, amount: float):
    idem_key = f"idem:refund:{order_id}"
    lock_key = f"lock:refund:{order_id}"

    # 1. 檢查是否已有「成功執行」的結果
    cached = await redis.get(idem_key)
    if cached:
        return json.loads(cached)

    # 1'. 上一次的結果未定（timeout / 連線中斷）就不能再打一次：
    #     交給對帳流程收尾，或帶同一個 idem key 去查金流端的真實結果
    if await redis.get(f"reconcile:refund:{order_id}"):
        raise NeedsReconciliation(order_id)

    # 2. 併發防護：搶占執行鎖。value 放一個「本次嘗試」的 owner token，
    #    這樣釋放時才能確認要刪的是自己的鎖（見下方 5a）
    owner = uuid.uuid4().hex
    acquired = await redis.set(lock_key, owner, nx=True, ex=LOCK_TTL)
    if not acquired:
        raise Exception("操作正在處理中，請勿重複送出")

    try:
        # 3. 執行業務邏輯
        result = await payment_api.refund(order_id, amount)

        # 4. 成功：存入 24HR 冪等快取
        await redis.setex(idem_key, 86400, json.dumps(result))
        return result

    except DefiniteFailure as e:
        # 5a. 確定失敗：只有金流端「明確拒絕且沒有產生副作用」才算（依它的錯誤碼
        #     契約判斷，不要只看 HTTP 4xx）。釋放鎖，允許重試 ——
        #     但要比對 owner token 再刪，否則租期過後可能刪掉別人的新鎖
        await redis.eval(
            "if redis.call('get', KEYS[1]) == ARGV[1] "
            "then return redis.call('del', KEYS[1]) else return 0 end",
            1, lock_key, owner,
        )
        raise e

    except (TimeoutError, ConnectionError) as e:
        # 5b. 結果未定：對方可能已經扣款了。**不要**釋放鎖，而且要先把
        #     「未定」寫成持久狀態（TTL 要長到蓋過所有重試窗，且由 1' 檢查），
        #     否則鎖一過期就有人能再打一次退款
        await redis.setex(f"reconcile:refund:{order_id}", IDEM_TTL, "UNKNOWN")
        raise e

        ┌─────────────┐
        │  請求進入    │
        └──────┬──────┘
               ▼
     ┌───────────────────┐   HIT    ┌──────────────────┐
     │ GET idem_key      │─────────▶│ 回傳上次成功結果  │
     └─────────┬─────────┘          └──────────────────┘
               │ MISS
               ▼
     ┌───────────────────┐   FAIL   ┌──────────────────┐
     │ SET lock NX EX 30 │─────────▶│ 429 處理中，請稍候│
     └─────────┬─────────┘          └──────────────────┘
               │ OK
               ▼
     ┌───────────────────┐
     │ 呼叫 payment_api  │
     └────┬─────────┬────┘
   成功    │         │  失敗
          ▼         ▼
  ┌──────────────┐ ┌──────────────────────────────┐
  │SETEX idem 24H│ │ 確定失敗 → DEL lock（可重試）│
  │ + DEL lock   │ │ 結果未定 → 留鎖 + 待對帳      │
  └──────────────┘ └──────────────────────────────┘

# python
if force_retry:
    await redis.delete(f"idem:refund:{order_id}")

order_1001
 ├── refund_request_A (退 $300) → idem:refund:req_A   ← 各自冪等
 ├── refund_request_B (退 $200) → idem:refund:req_B
 └── refund_request_C (退 $100) → idem:refund:req_C

-- 用 unique constraint 讓 DB 幫你擋掉重複寫入
CREATE TABLE refunds (
    id                BIGINT PRIMARY KEY AUTO_INCREMENT,
    order_id          VARCHAR(64) NOT NULL,
    idempotency_key   VARCHAR(255) NOT NULL,
    amount            DECIMAL(10,2) NOT NULL,
    status            VARCHAR(20) NOT NULL,
    result_payload    JSON,
    created_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_idem (idempotency_key)
);

# python
# Redis miss 時仍可能併發 → 靠 DB unique index 收尾
try:
    await db.insert_refund(idempotency_key=key, order_id=order_id, amount=amount)
except UniqueViolation:
    return await db.get_refund_result(key)   # 已存在 → 回傳既有結果