agentsop-llm-tool-idempotency

LLM Tool Idempotency · SOP

One-liner: The LM is at-least-once; the tool must be at-most-once. Every framework that promises "durable execution" still re-runs node bodies on resume. Every HTTP client retries on timeout. Every model occasionally emits the same tool_call twice. Idempotency belongs in the tool, not in a wish.

---

1. 何时激活 (Activation Rules)

Activate this skill when any of the following triggers fire:

• You're defining a tool whose name contains send_, create_, charge_, post_, write_, publish_, transfer_, delete_, update_, or notify_.
• The tool wraps a third-party API call (Stripe, SendGrid, Twilio, Slack, Discord webhook, S3 PUT, payment gateway, internal write API).
• You're inside a LangGraph node that contains an interrupt(...) call AND a side effect in the same function body — the resume re-runs the body from the top [langgraph/gotchas].
• The tool is invoked through MCP, OpenAI tool-calling, Anthropic tool use, CrewAI delegation, or any layer where a transport timeout could be interpreted as "retry" even though the operation succeeded server-side.
• The user reports "the agent sent it twice" / "charge appeared twice" / "duplicate row" / "got two emails".
• Your test harness records the same (tool_name, args_hash) invoked more than once within a single user turn.

Do not activate when the tool is read-only (GET-equivalent), or when the side effect is genuinely commutative AND verified safe under duplication.

---

2. 核心心智模型 (Core Mental Model)

2.1 The fundamental asymmetry

   LM tool-call semantics       Tool side-effect semantics
   ─────────────────────        ─────────────────────────
   At-least-once delivery       Must be at-most-once
   (network retry, framework    (one charge, one email,
    resume, model dup-emit,      one record)
    user re-prompt)
        │                                │
        └────── gap to bridge ───────────┘
                       ↓
              IDEMPOTENCY KEY
       (a stable identifier the LM
        commits to BEFORE the call,
        which the tool dedupes on)