Side Effects and Idempotency

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