Reintentar es un hecho. Cobrar dos veces no.

En un agente, las tools se reintentan. Mucho. Las razones:

• Timeouts de red (la primera llamada se perdió en el aire).
• El agente cambia de opinión en medio de un turno y vuelve a invocar.
• Un retry handler genérico que vos ni armaste y igual está corriendo.
• El modelo, viendo un error ambiguo, vuelve a probar.

Si la tool tiene side effects (crea un registro, cobra plata, manda un mail), reintentar sin protección significa: dos registros, doble cobro, dos mails. Para el usuario, eso es un bug en producción que cuesta confianza y dinero.

La solución es idempotencia: diseñar la tool de modo que llamarla N veces con los mismos parámetros equivale a llamarla 1 vez.

Las tres formas de hacer una tool idempotente

1. Naturalmente idempotente. Algunas operaciones ya lo son. set_status("active") llamada 5 veces deja el mismo estado. No hace falta hacer nada extra.

2. Por idempotency_key. El cliente (o el agente) genera una key única por intent, y la pasa. El servidor recuerda esa key y el resultado. Si la key se repite, devuelve el resultado anterior sin re-ejecutar. Este es el patrón canónico para crear cosas (pagos, órdenes, registros).

3. Por chequeo de estado. Antes de actuar, el handler chequea si el efecto ya ocurrió. assign_shift puede chequear si el crewmate ya está asignado a ese turno y, si sí, devolver { ok: true, already_assigned: true }.

El contrato de idempotency_key

Cuando soportás idempotency_key:

• Documentalo en la description del tool. El agente lo aprende y empieza a generar keys con req-{uuid} o similar.
• Marcalo opcional (no required). Algunos clientes no la pasan; eso es válido pero implica "sin protección".
• Devolvé un flag replayed o equivalente. El agente necesita saber si la operación creó algo nuevo o devolvió un resultado existente.
• Guardá la asociación key → resultado persistentemente. Si solo lo guardás en memoria, un retry después de un restart pierde la protección.

Patrón en código

async function handle({ ..., idempotency_key }) {
  if (idempotency_key) {
    const prev = await db.payments.findByIdempotencyKey(idempotency_key);
    if (prev) {
      return { ok: true, payment_id: prev.payment_id, replayed: true };
    }
  }
  const payment = await db.payments.create({ ..., idempotency_key });
  return { ok: true, payment_id: payment.payment_id, replayed: false };
}

Tu tarea

A la derecha tenés register_payment. El starter cobra cada vez que se llama. Convertilo en idempotente.

En agentes que tocan dinero, estado externo, o humanos, la idempotencia no es opcional. Es la diferencia entre un sistema que se puede operar y un sistema que da soporte cada semana porque "se duplicó".