Side-effecting agent tool not idempotent when the call is retried

Give every side-effecting tool an idempotency key derived from the tool call, so a retry has its effect once.

In each tool function that changes an external system (payments, refunds, transfers, e-mail, SMS, chat sends, order or ticket creation), derive an idempotency key from the run and the tool-call id (or from the business key, such as order id plus action) and pass it to the downstream API (Stripe idempotency_key=, an Idempotency-Key header, SQS MessageDeduplicationId), or record the key in your own store and return the stored result when it is seen again. Do the same for framework-level retries (LangGraph RetryPolicy, tenacity @retry) around those tools.

Where it goes: 1 application source code, 6 API calls and integrations, 15 agent action surface.

What reviewers look for: idempotency_key= or an Idempotency-Key header on payment, refund, send and create calls inside tool functions, with the key built from the tool-call or task id; or a processed-keys check before the side effect.

@tool
def refund_order(order_id: str, amount: int) -> str:
    stripe.Refund.create(payment_intent=lookup(order_id), amount=amount)
    return 'refunded'

@tool
def refund_order(order_id: str, amount: int, tool_call_id: str) -> str:
    stripe.Refund.create(payment_intent=lookup(order_id), amount=amount,
                         idempotency_key=f'refund:{order_id}:{tool_call_id}')   # a retry refunds once
    return 'refunded'

Engineering guidance, not legal advice. Each provision below may add its own details (a cadence, a deadline, a required notice element): open it for those.