DEV Community

Cover image for Por qué fallan los agentes de IA en producción y cómo probar cada modo de fallo
Roobia
Roobia

Posted on • Originally published at apidog.com

Por qué fallan los agentes de IA en producción y cómo probar cada modo de fallo

Tu agente funcionó en la demo: leyó el ticket, llamó a tres APIs y publicó un resumen limpio. Una semana después, envió dos correos al mismo cliente, agotó el presupuesto diario de tokens en un bucle de reintentos y devolvió a tu frontend una carga útil imposible de analizar.

Prueba Apidog hoy

La diferencia entre un prototipo y un agente fiable no suele estar en el modelo ni en el prompt. Está en la integración: cada herramienta que invoca el agente termina siendo una solicitud HTTP que puede fallar, expirar, recibir límites de tasa o devolver datos inesperados. Si no pruebas esas llamadas como pruebas cualquier API de producción, basta una respuesta incorrecta para provocar un incidente.

La buena noticia es que la fiabilidad se puede probar. En lugar de esperar a que tus usuarios descubran las rutas de fallo, simúlalas antes. Esta guía agrupa los fallos más comunes en cinco modos y muestra cómo probarlos en el límite de la API. Apidog permite definir contratos, simular dependencias y validar respuestas para estos escenarios.

Los agentes fallan en el límite de la API, no en el prompt

Cuando un agente falla en producción, el primer impulso suele ser editar el prompt. A veces funciona, pero muchas incidencias tienen otro origen: el agente recibió una respuesta lenta, mal formada, limitada por tasa o con una estructura distinta de la esperada.

Un paso típico de un agente incluye:

  1. El modelo elige una herramienta.
  2. Tu aplicación transforma esa elección en una solicitud HTTP.
  3. Un servicio externo responde.
  4. Tu aplicación devuelve el resultado al modelo.

De esos cuatro pasos, tres son integración API convencional. La diferencia es que el modelo puede razonar sobre una entrada errónea y continuar con una acción incorrecta, en lugar de detenerse con una excepción clara.

La pregunta útil no es “¿es suficientemente inteligente el modelo?”, sino:

¿He probado las formas en que las llamadas API de mi agente pueden fallar?

Estas cinco categorías cubren la mayoría de los casos.

Modo de fallo 1: llamadas a herramientas que se desvían del contrato

El agente puede generar una llamada que no coincide con la API real: inventa parámetros, omite campos obligatorios, envía tipos incorrectos o combina argumentos incompatibles.

Por ejemplo, un agente de reservas podría llamar a POST /reservations así:

{
  "guests": "two",
  "date": "2025-07-14"
}
Enter fullscreen mode Exit fullscreen mode

Si la API espera un entero, el contrato debería exigir:

{
  "guests": 2,
  "date": "2025-07-14"
}
Enter fullscreen mode Exit fullscreen mode

Una API bien diseñada devolverá un 400. Una integración frágil puede devolver un 200 con un error incrustado en el cuerpo, y el agente puede interpretarlo como un éxito.

Cómo probarlo

  1. Define un esquema para cada herramienta disponible para el agente.
  2. Valida las solicitudes salientes contra ese esquema.
  3. Haz que cualquier incumplimiento falle explícitamente en CI.
  4. Verifica también el cuerpo de respuesta, no solo el código HTTP.

Ejemplo de contrato OpenAPI simplificado:

paths:
  /reservations:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - guests
                - date
              properties:
                guests:
                  type: integer
                  minimum: 1
                date:
                  type: string
                  format: date
Enter fullscreen mode Exit fullscreen mode

Consulta la guía sobre cómo probar las llamadas a herramientas de un agente de IA y el flujo completo para probar agentes que llaman a tus APIs.

El paso práctico es cargar los contratos de tus herramientas en Apidog y ejecutar las llamadas reales del agente contra esos contratos. Así puedes detectar exactamente qué campo, tipo o restricción se rompió.

Modo de fallo 2: errores upstream y límites de tasa

Cada dependencia externa puede devolver:

  • 429 Too Many Requests
  • 500 Internal Server Error
  • Un tiempo de espera
  • Una conexión cerrada
  • Una respuesta parcial o vacía

Un agente robusto necesita reintentos controlados, retroceso exponencial y un límite de intentos. Un agente frágil se rinde demasiado pronto o reintenta sin control hasta agotar presupuesto y aumentar la carga sobre el proveedor.

La discusión sobre patrones para la recuperación de errores de agentes muestra lo frecuente que es este problema.

Cómo probar la recuperación

No basta con probar contra una API saludable. Debes simular una secuencia de fallos, por ejemplo:

  1. Primer intento: 429 con Retry-After.
  2. Segundo intento: 500.
  3. Tercer intento: 200 OK.

Después, valida que el agente:

  • Respeta Retry-After.
  • Aplica retroceso exponencial con variación.
  • No excede el máximo de reintentos.
  • Registra el error de forma observable.
  • Deja de llamar si se activa un disyuntor.
  • No duplica una operación con efectos secundarios.

Una estrategia básica de reintento podría verse así:

const maxRetries = 3;

for (let attempt = 0; attempt < maxRetries; attempt++) {
  const response = await callTool();

  if (response.ok) {
    return response.data;
  }

  if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After");
    await sleep(Number(retryAfter ?? 1) * 1000);
    continue;
  }

  if (response.status >= 500) {
    const delay = 2 ** attempt * 1000;
    await sleep(delay + Math.random() * 250);
    continue;
  }

  throw new Error(`Error no recuperable: ${response.status}`);
}

throw new Error("Máximo de reintentos alcanzado");
Enter fullscreen mode Exit fullscreen mode

Si la acción se puede repetir —por ejemplo, crear un pago o enviar un correo—, usa una clave de idempotencia. Sin ella, un reintento puede duplicar el efecto.

También conviene ensayar explícitamente los límites de tasa. Revisa qué significa una respuesta de límite de tasa excedido y aplica los patrones de recuperación de errores de agentes de IA.

Modo de fallo 3: salida no determinista

Incluso con temperatura cero, una salida de LLM no siempre será idéntica byte a byte entre ejecuciones. El hardware, el procesamiento por lotes y los cambios del proveedor pueden introducir variaciones. El hilo de vLLM sobre semillas y temperatura ilustra este problema.

Si tus pruebas comparan texto completo, acabarás con pruebas inestables. Y las pruebas inestables terminan ignorándose.

Qué afirmar en lugar del texto exacto

Prueba estructura, restricciones y significado:

  • El resultado cumple un esquema JSON.
  • La herramienta seleccionada es la esperada.
  • Los argumentos tienen tipos válidos.
  • Los números están dentro de un rango.
  • Existen claves obligatorias.
  • No aparecen campos prohibidos.

En lugar de esto:

expect(response.summary).toBe(
  "El pedido #1234 se entregará el martes."
);
Enter fullscreen mode Exit fullscreen mode

Usa validaciones de estructura:

expect(response).toMatchObject({
  status: "ok",
  orderId: "1234"
});

expect(response.estimatedDays).toBeGreaterThanOrEqual(1);
expect(response.estimatedDays).toBeLessThanOrEqual(7);
Enter fullscreen mode Exit fullscreen mode

O valida contra un esquema:

const resultSchema = z.object({
  status: z.enum(["ok", "needs_review"]),
  total: z.number().min(0),
  currency: z.string().length(3),
  summary: z.string().min(1)
});

resultSchema.parse(response);
Enter fullscreen mode Exit fullscreen mode

Una prueba que verifica que total está entre 0 y el importe del carrito tolera variación natural del modelo, pero sigue detectando una regresión real.

Consulta cómo probar agentes de IA no deterministas, además de cómo funciona la memoria del agente, porque el estado persistente añade más variables a las pruebas.

Modo de fallo 4: costo descontrolado

Los agentes entran en bucles, y los bucles cuestan dinero. Un agente que reintenta una llamada fallida miles de veces puede transformar una carga pequeña en una factura importante.

El costo también es un problema de fiabilidad: los patrones que desperdician tokens —reintentos redundantes, contexto excesivo y llamadas repetidas— hacen que el agente sea más lento e impredecible.

Controles mínimos de costo

Mide y limita al menos estas variables por ejecución:

type AgentRunMetrics = {
  toolCalls: number;
  retryCount: number;
  inputTokens: number;
  outputTokens: number;
  estimatedCost: number;
};
Enter fullscreen mode Exit fullscreen mode

Aplica límites antes de ejecutar acciones adicionales:

if (metrics.toolCalls > 10) {
  throw new Error("Límite de llamadas a herramientas excedido");
}

if (metrics.estimatedCost > taskBudget) {
  throw new Error("Presupuesto de tarea excedido");
}
Enter fullscreen mode Exit fullscreen mode

Además:

  • Define un presupuesto máximo por tarea.
  • Limita la profundidad o el número de pasos del agente.
  • Cachea resultados que no necesitan recalcularse.
  • Registra llamadas repetidas con los mismos argumentos.
  • Incluye el número total de llamadas en las aserciones de tus pruebas.

Un agente que completa una tarea después de cuarenta llamadas no necesariamente ha pasado una prueba de fiabilidad. Puede ser un incidente de costo pendiente.

La guía sobre cómo reducir los costos de tokens del agente reúne palancas concretas para reducir consumo.

Modo de fallo 5: ausencia de barandillas de seguridad

Los fallos más caros ocurren cuando el agente hace exactamente lo que se le indicó, pero esa acción no debería haberse ejecutado sin controles: enviar un correo, borrar un registro, modificar permisos o realizar un pedido.

Las barandillas de seguridad separan la decisión del modelo de la acción irreversible.

Implementa una capa de aprobación

Clasifica las herramientas según su impacto:

const tools = {
  searchCustomer: { requiresApproval: false },
  draftEmail: { requiresApproval: false },
  sendEmail: { requiresApproval: true },
  deleteRecord: { requiresApproval: true }
};
Enter fullscreen mode Exit fullscreen mode

Antes de ejecutar una acción sensible, detén el flujo:

if (tools[toolName].requiresApproval) {
  return {
    status: "needs_approval",
    proposedAction: toolName,
    arguments: toolArgs
  };
}
Enter fullscreen mode Exit fullscreen mode

También necesitas un modo de ejecución en seco:

if (dryRun) {
  return {
    status: "dry_run",
    action: toolName,
    arguments: toolArgs
  };
}
Enter fullscreen mode Exit fullscreen mode

Cómo probar las barandillas

  1. Simula el endpoint con efectos secundarios.
  2. Pide al agente una acción sensible.
  3. Verifica que el agente entra en la ruta de aprobación.
  4. Confirma que no se ejecutó ninguna solicitud real al endpoint.
  5. Prueba también el flujo aprobado y audita los argumentos finales.

La OWASP Top 10 para aplicaciones de modelos de lenguaje grandes es una buena lista de comprobación para identificar riesgos. Para implementar puertas de aprobación y limitar el radio de explosión, revisa barandillas de seguridad para agentes de IA.

Cómo estructurar una prueba de agente

Los cinco modos de fallo comparten la misma estructura. Puedes reutilizar este ciclo para cada herramienta:

  1. Captura el contrato de cada herramienta que el agente puede invocar.
  2. Simula la dependencia para controlar códigos de estado, latencia y cuerpos de respuesta.
  3. Ejecuta el escenario contra el agente, incluidas las rutas infelices.
  4. Afirma el comportamiento: solicitud enviada, recuperación, número de llamadas, presupuesto y activación de barandillas.

Una matriz de pruebas útil puede ser esta:

Escenario Simulación Aserción principal
Contrato inválido 400 por campo incorrecto El agente no continúa como si hubiera éxito
Límite de tasa 429 con Retry-After Respeta espera y limita reintentos
Error upstream 500 seguido de 200 Se recupera sin duplicar acciones
Tiempo de espera Sin respuesta dentro del límite Cancela o reintenta de forma controlada
Acción destructiva Endpoint simulado de borrado Solicita aprobación antes de ejecutar
Respuesta variable Variaciones válidas de JSON El esquema sigue siendo válido

Empieza con una herramienta, automatiza sus escenarios y añade la siguiente. La inversión se recupera la primera vez que una prueba detecta una llamada rota antes que un usuario.

Lista de verificación de fiabilidad del agente

Antes de desplegar un agente, comprueba lo siguiente:

  • [ ] Cada llamada a herramienta se valida contra un esquema.
  • [ ] Las violaciones de contrato fallan una prueba.
  • [ ] Se simulan respuestas 429, 500 y tiempos de espera.
  • [ ] Los reintentos usan retroceso exponencial y tienen un límite.
  • [ ] Las acciones reintentadas son idempotentes.
  • [ ] Las pruebas validan estructura y significado, no texto exacto.
  • [ ] Se mide el uso de tokens por ejecución.
  • [ ] Existe un presupuesto máximo por tarea.
  • [ ] Las acciones destructivas requieren lista blanca o aprobación humana.
  • [ ] La ruta de seguridad se prueba contra una simulación.

Si completas esta lista, habrás cubierto las formas más frecuentes en que los agentes fallan en producción.

Dónde encaja Apidog y dónde no

Conviene ser preciso sobre el alcance de la herramienta. Apidog no es un framework de agentes, un host de modelos ni un arnés de evaluación. No construye ni ejecuta tu agente.

Su papel está en la capa API:

  • Diseñar y almacenar contratos para las herramientas del agente.
  • Validar solicitudes salientes contra esos contratos.
  • Simular dependencias y respuestas de fallo.
  • Probar escenarios con 429, 500, tiempos de espera y cuerpos mal formados.
  • Verificar esquemas, rangos y campos obligatorios en las respuestas.

En otras palabras, Apidog prueba las APIs que usa tu agente, simula los fallos que debes manejar y valida lo que el agente recibe. Para una perspectiva más amplia, consulta la guía de pruebas de IA agéntica.

Preguntas frecuentes

¿La fiabilidad de un agente es un problema del modelo o de ingeniería?

Principalmente de ingeniería. El modelo importa, pero los incidentes habituales —llamadas inválidas, límites de tasa sin gestionar, reintentos descontrolados y falta de aprobación— son problemas de integración y pruebas.

¿Puedo probar un agente sin usar las APIs reales?

Sí, y deberías hacerlo. Simula las dependencias para controlar errores, latencias y efectos secundarios. Es la forma fiable de probar recuperación y barandillas de seguridad.

¿Cómo pruebo una salida que cambia en cada ejecución?

Valida estructura y significado. Usa esquemas JSON, tipos, campos requeridos, rangos numéricos y restricciones sobre herramientas o argumentos. Evita comparar respuestas completas como cadenas exactas.

Para más detalles, consulta cómo probar agentes de IA no deterministas.

¿Qué debería probar primero?

Empieza por las acciones destructivas y la recuperación de errores. Son los dos escenarios con mayor impacto: un agente que realiza una acción dañina y un agente que entra en bucle hasta agotar el presupuesto.

Empieza con un modo de fallo

No necesitas cubrir los cinco modos en una semana. Elige el riesgo más relevante para tu caso, normalmente las barandillas de seguridad o la recuperación ante errores upstream.

Programa una simulación, ejecuta el agente y mide su comportamiento:

  • ¿Cuántas llamadas realizó?
  • ¿Cuánto esperó entre reintentos?
  • ¿Respetó el presupuesto?
  • ¿Pidió aprobación?
  • ¿Intentó ejecutar una acción con efectos secundarios?

La primera vez que veas a tu agente manejar un 429 simulado con un retroceso controlado, en lugar de entrar en un bucle costoso, tendrás una razón real para confiar en él.

Descarga Apidog para diseñar contratos, simular fallos y validar las respuestas de las que depende tu agente.

Top comments (0)