Lesson 11 / 25
Side Effects and Idempotency
Make write tools safe to retry and clear about what they change.
By Rahul Agarwal · 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.