Idempotencia en agentes de IA: reintentos seguros sin duplicar acciones

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Checklist

TypeScript: intent durable y clave determinista

Este pseudocódigo concentra el contrato. `insertIfAbsent` debe tener una restricción única sobre la clave; `compareAndSet` evita que dos workers ejecuten el mismo intent a la vez. El proveedor recibe la misma clave cuando ofrece soporte nativo.

import { createHash } from "node:crypto";

function keyFor(x: { tenant: string; actor: string; tool: string; resource: string; args: unknown }) {
  const canonical = canonicalJson(x.args);
  return createHash("sha256").update([x.tenant, x.actor, x.tool, x.resource, canonical].join("|")).digest("hex");
}

async function execute(input: ToolInput) {
  const key = keyFor(input);
  const hash = hashPayload(input.args);
  const row = await db.insertIfAbsent({ key, hash, status: "received", input });
  if (row && row.hash !== hash) throw new Error("idempotency_conflict");
  if (row?.status === "succeeded" || row?.status === "failed") return row.result;
  if (!(await policy.allows(input)) || !(await approval.granted(input))) {
    await db.transition(key, "rejected"); return { status: "rejected" };
  }
  if (!(await db.compareAndSet(key, ["received", "unknown"], "running"))) return db.read(key);
  try {
    const result = await provider.mutate(input.args, { idempotencyKey: key });
    await db.transition(key, "succeeded", { result, providerId: result.id });
    return result;
  } catch (error) {
    const kind = classify(error); // transient | permanent | unknown
    await db.transition(key, kind === "transient" ? "failed_transient" : "unknown", { error: safe(error) });
    throw error;
  }
}

Un worker recoge `failed_transient` con backoff y límite; no conserva una petición HTTP abierta. Si el proceso muere después de que el proveedor acepta pero antes de guardar `succeeded`, el siguiente worker empieza en `unknown` y reconcilia antes de mutar otra vez.

Puntos a revisar

Lo que conviene comprobar

AWS Step Functions separa errores recuperables, backoff y destinos de fallo; adopta esa disciplina aunque uses una cola propia. Para workflows largos, una máquina durable suele ser más segura que esconder reintentos dentro de HTTP. Las [evals de trayectorias](/evals-agentes-ia-tools-trayectorias/) deben comprobar que el agente no insiste con `unknown` sin reconciliar.

Checklist

Conclusión

La unidad fiable de un agente no es el mensaje ni la llamada de función: es la intención durable que puede autorizarse, ejecutarse, repetirse y reconciliarse sin perder identidad. Si no distingues “no se envió” de “se envió pero perdimos la respuesta”, todavía no estás listo para mutar datos reales.

Fuentes y referencias

• OpenAI: programmatic tool calling
• OpenAI Agents SDK: function tools
• OpenAI Agents SDK: errores
• Stripe: idempotent requests
• AWS Step Functions: error handling
• AWS Step Functions: workflow type

También te puede interesar

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.