Por Qué Tu Agente de IA Sigue Fallando en Producción (Y Cómo Arreglarlo)

Tabla de contenidos

Actualizado junio 2026.

TL;DR: La mayoría de los fallos de agentes en producción provienen de cinco causas: prompts frágiles que no manejan casos extremos, falta de lógica de reintento para errores de API transitorios, sin observabilidad para ver qué está fallando, bucles descontrolados sin condición de salida y definiciones de herramientas suficientemente ambiguas como para que el modelo elija la equivocada. Los cinco son solucionables sin cambiar modelos ni frameworks.

[Lectura del operador] Tengo más de 30 agentes en producción. He tenido todos estos fallos. Los que me quemaron más tiempo no fueron los exóticos — fueron los fallos de infraestructura aburridos que pensé que había manejado.

Fallo 1: Prompts frágiles que se rompen con entradas de casos extremos

Un prompt que funciona en tus casos de prueba fallará con entradas que no anticipaste. Eso no es una limitación del modelo — es un problema de escritura de instrucciones.

Síntomas: El agente produce resultados sin sentido, llama a la herramienta equivocada o genera JSON malformado cuando la entrada es ligeramente diferente a lo que probaste.

Causa raíz: Tu system prompt describe solo el camino feliz. No le dice al modelo qué hacer cuando los datos faltan, están malformados o son ambiguos.

Solución: Añade manejo explícito de casos extremos a tu system prompt:

If the input data is missing a required field, return:
{ "status": "error", "reason": "missing_field", "field": "<fieldname>" }
Do NOT attempt to infer or hallucinate missing values.

If you are uncertain which tool to call, call no tool and return:
{ "status": "clarification_needed", "question": "..." }

El modelo sigue instrucciones explícitas para casos extremos de manera confiable. El error es asumir que generalizará las instrucciones del camino feliz para manejar los casos complicados.

Fallo 2: Sin lógica de reintento para errores transitorios de API

Cada API externa que llama tu agente fallará en algún momento. La API de Claude, la Meta Graph API, tu base de datos — todas devuelven errores 5xx, se agota el tiempo de espera o limitan la velocidad. Si tu agente no tiene lógica de reintento, un error transitorio mata toda la ejecución.

Síntomas: Las ejecuciones del agente fallan aleatoriamente en diferentes pasos. Los registros muestran un 503 o 429 sin intento posterior.

Solución: Envuelve cada llamada externa en un reintento con retroceso exponencial:

async function withRetry<T>(fn: () => Promise<T>, retries = 3, baseDelayMs = 500): Promise<T> {
  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      const isTransient = err.status === 429 || err.status >= 500 || err.code === "ECONNRESET";
      if (!isTransient || attempt === retries) throw err;
      const delay = baseDelayMs * Math.pow(2, attempt) + Math.random() * 100;
      await new Promise((r) => setTimeout(r, delay));
    }
  }
  throw new Error("unreachable");
}

// Usage
const result = await withRetry(() => client.messages.create({ ... }));

Tres reintentos con retroceso exponencial maneja ~99% de los fallos transitorios. Añade esto a cada llamada externa y la mitad de tus fallos aleatorios desaparecerán.

Fallo 3: Sin observabilidad — no puedes ver qué está fallando

Este es el modo de fallo más común en producción y el que más tiempo cuesta depurar: el agente falla silenciosamente o produce resultados incorrectos, y no tienes idea de dónde en la cadena salió mal.

Síntomas: Sabes que algo está mal pero no puedes identificar el paso. Añades declaraciones console.log y vuelves a ejecutar manualmente intentando reproducir.

Solución: Registro estructurado en cada paso, con un ID de ejecución que traza toda la ejecución:

function createLogger(runId: string, agentName: string) {
  return {
    step: (step: string, data: object) =>
      console.log(JSON.stringify({ runId, agent: agentName, step, ts: new Date().toISOString(), ...data })),
    error: (step: string, err: unknown) =>
      console.error(JSON.stringify({ runId, agent: agentName, step, error: String(err), ts: new Date().toISOString() })),
  };
}

const log = createLogger(crypto.randomUUID(), "newsletter-agent");
log.step("fetch_topic", { topicId: topic.id, topic: topic.name });
// ... do work ...
log.step("draft_complete", { subject: draft.subject, wordCount: draft.body.split(" ").length });

Si estás en Cloudflare Workers, estos registros van a Logpush o Workers Tail. Si estás ejecutando localmente o en un VPS, canaliza a un agregador de registros. El JSON estructurado significa que puedes filtrar por runId para ver exactamente qué sucedió en una sola ejecución.

Fallo 4: Bucles descontrolados sin condición de salida

Los bucles agénticos — donde el modelo llama a herramientas e itera hasta que se cumple una condición — pueden ejecutarse para siempre si esa condición nunca se cumple o el modelo la identifica incorrectamente.

Síntomas: El agente gasta cientos de dólares en costos de API antes de agotar el tiempo de espera. O ejecuta la misma llamada de herramienta una y otra vez sin progresar.

Solución: Siempre ten un límite de iteración duro y una verificación de progreso:

const MAX_ITERATIONS = 10;
let iterations = 0;
let lastToolCallName = "";
let sameToolCallCount = 0;

while (true) {
  iterations++;
  if (iterations > MAX_ITERATIONS) {
    log.error("loop", { reason: "exceeded_max_iterations" });
    break;
  }

  const response = await client.messages.create({ ... });

  // Detect stuck loops: same tool called 3x in a row
  const toolCall = response.content.find(b => b.type === "tool_use");
  if (toolCall?.name === lastToolCallName) {
    sameToolCallCount++;
    if (sameToolCallCount >= 3) {
      log.error("loop", { reason: "stuck_loop", tool: toolCall.name });
      break;
    }
  } else {
    sameToolCallCount = 0;
    lastToolCallName = toolCall?.name ?? "";
  }

  if (response.stop_reason === "end_turn") break;
}

Esto captura tanto los modos de fallo de “se ejecutó demasiado tiempo” como de “giró en el lugar”. El límite debe ser lo suficientemente generoso para el camino feliz pero lo suficientemente ajustado para limitar el radio de explosión.

Fallo 5: Definiciones de herramientas ambiguas que el modelo resuelve mal

Si le das al modelo dos herramientas con descripciones superpuestas, a veces llamará a la equivocada. Esto es especialmente común con herramientas como search_database vs get_record o send_email vs create_draft.

Síntomas: El modelo llama a la categoría correcta de herramienta pero elige la específica equivocada. O llama a una herramienta en el contexto equivocado (usando una herramienta de escritura cuando solo era apropiada la lectura).

Solución: Haz las descripciones de herramientas mutuamente excluyentes y añade explícitamente “cuándo NO usar esto”:

const tools = [
  {
    name: "get_subscriber",
    description: "Fetch a single subscriber record by email. Use ONLY when you have a specific email address. Do NOT use for searching or listing subscribers.",
    input_schema: { ... }
  },
  {
    name: "search_subscribers",
    description: "Search subscribers by tag, segment, or status. Use when you need to find subscribers matching a criteria — NOT when you have a specific email address.",
    input_schema: { ... }
  }
];

La cláusula “NO usar cuando X” es la parte que la mayoría omite. Es la parte más importante. Los modelos son mejores siguiendo restricciones negativas explícitas que infiriéndolas de descripciones positivas.

Una cosa más: prueba tus agentes con entradas malas

La mayoría de los agentes se prueban solo con entradas limpias de camino feliz. La producción tiene entradas sucias: cadenas vacías, campos nulos, casos extremos de Unicode, respuestas de API que devuelven 200 pero con un esquema inesperado.

Añade una suite de pruebas que ejercite explícitamente:

• Entradas vacías o nulas
• Entradas en la longitud máxima que esperarías
• Entradas con caracteres especiales o texto no ASCII
• APIs externas devolviendo formas de respuesta inesperadas

Si tu agente se rompe con alguna de estas, arréglalo antes de que salga en vivo. El entorno de producción encontrará cada suposición que hayas hecho.

La conclusión del operador

La mayoría de los fallos de agentes en producción son problemas de infraestructura disfrazados de problemas de modelo. Antes de cambiar modelos, añade reintentos, registro estructurado, límites de bucle y manejo explícito de casos extremos a tus prompts. Arregla las definiciones de herramientas ambiguas. Luego prueba con entradas malas. Haz todo eso antes de culpar al modelo — en mi experiencia, el modelo suele ser lo último que necesita cambio.