Lesson 11 / 25

Side Effects and Idempotency

Make write tools safe to retry and clear about what they change.

By · 15 years in web development

Assume the call may repeat

Agents retry, loops resume after crashes, and models sometimes repeat a call. A tool that "creates an order" will create two. Make writes idempotent: accept an idempotency key or check for an existing record, so repeating the same request has the same effect as doing it once. Label tools as read-only or state-changing so approval rules can target them.

An idempotent create

The key makes a repeated call return the existing order instead of creating a duplicate. db is your data layer.

@tool
def create_order(customer_id: int, item: str, request_key: str) -> str:
    """Create an order. Safe to retry with the same request_key. Changes data."""
    existing = db.find_order_by_key(request_key)
    if existing:
        return f"order {existing.id} (already created)"
    order = db.insert_order(customer_id, item, request_key)
    return f"order {order.id} created"

Quick check: What does an idempotency key achieve?

  • It encrypts the request
  • It hides the tool from the model
  • It speeds up the database
  • Repeating the request does not create a duplicate effect
Answer

Repeating the request does not create a duplicate effect — The same key identifies the same logical request, so retries are safe.