Tu agente funcionó en la demo. Leyó el ticket, llamó a tres APIs y publicó un resumen limpio. Luego lo lanzaste. Una semana después, envió un correo electrónico al mismo cliente dos veces, agotó el presupuesto de tokens de un día en un bucle de reintentos y entregó a tu frontend una carga útil que no pudo analizar.
Esa brecha entre un prototipo funcional y un agente fiable es donde la mayoría de los equipos se quedan atascados. El modelo rara vez es el culpable. El problema reside en la parte que se trata como fontanería: las llamadas a la API que el agente realiza en busca de una respuesta. Un agente es un bucle de llamadas a herramientas, y cada llamada a una herramienta es una solicitud HTTP que puede fallar, limitarse, expirar o devolver algo que no esperabas. Si omites probar esas llamadas de la misma manera que pruebas cualquier API de producción, tu agente está a una respuesta errónea de causar un incidente.
Aquí está la parte tranquilizadora: la fiabilidad del agente es comprobable. No tienes que confiar en que el modelo se comporte bien. Ejercitas intencionadamente las rutas de fallo, antes de que tus usuarios las encuentren por ti. Esta guía clasifica los fallos del agente en cinco modos y muestra cómo detectar cada uno. El trabajo ocurre en el límite de la API, por lo que necesitas una plataforma que puedas apuntar a las dependencias del agente para diseñar el contrato, simular los fallos y verificar lo que se devuelve. Apidog cubre ese trabajo y lo utiliza en los ejemplos a continuación.
Los agentes fallan en el límite de la API, no en el prompt
Cuando un agente se comporta mal en producción, el instinto es editar el prompt. A veces eso ayuda. Más a menudo, el fallo no tiene nada que ver con la redacción. El agente solicitó algo a una API real, y la respuesta fue lenta, mal formada, limitada por tasa, o con una estructura diferente a la que el agente esperaba. El modelo entonces razonó sobre una entrada incorrecta e hizo algo seguro pero erróneo.
Mira lo que implica un solo paso de un agente. El modelo elige una herramienta. Tu código convierte esa elección en una solicitud HTTP. Un servicio externo responde. Tu código devuelve el resultado al modelo. Cuatro traspasos, y tres de ellos son integración API ordinaria, no aprendizaje automático. Eso es una buena noticia, porque la integración API es un problema de pruebas resuelto. Ya sabes cómo simular un endpoint lento o cómo afirmar un esquema JSON. Los agentes aumentan las apuestas, porque el modelo actúa sobre lo que recibe en lugar de lanzar una excepción limpia.
Así que la cuestión de la fiabilidad no es "es el modelo lo suficientemente inteligente". Es "he probado todas las formas en que las llamadas a la API del agente pueden salir mal". Cinco modos cubren la mayor parte.
Modo de fallo 1: Llamadas a herramientas que se desvían del contrato
El fallo más común de un agente es una llamada a una herramienta que no coincide con la API a la que llama. El modelo inventa un parámetro, omite un campo requerido, envía una cadena donde el esquema espera un entero, o llama al endpoint correcto con argumentos que no tienen sentido. Por ejemplo, un agente de reservas llama a POST /reservations con guests: "two" en lugar de guests: 2. La API devuelve un 400, o peor, un 200 con un error oculto en el cuerpo, y el agente sigue como si hubiera tenido éxito.
Esto se detecta probando la llamada a la herramienta como un contrato. Define el esquema para cada herramienta que el agente puede invocar, luego afirma que la solicitud saliente coincide: campos requeridos presentes, tipos correctos, enumeraciones válidas. Cuando el agente produce una llamada que rompe el contrato, quieres que eso falle ruidosamente en una prueba, no silenciosamente en producción. Nuestra guía sobre cómo probar las llamadas a herramientas de un agente de IA profundiza en esto, y el método más amplio para probar agentes que llaman a tus APIs cubre la configuración de principio a fin.
El paso práctico: captura los esquemas de herramientas que utiliza tu agente, cárgalos en Apidog y ejecuta las llamadas reales a herramientas del agente contra esas definiciones. Las discrepancias se manifiestan como fallos de validación que nombran el campo exacto que se rompió.
Modo de fallo 2: Errores upstream y límites de tasa
Cada llamada externa que el agente realiza puede devolver un 429, un 500 o nada en absoluto antes de un tiempo de espera. Un agente bien construido maneja esto con reintentos y retroceso exponencial. Uno frágil o bien se rinde al primer error o, lo que es más peligroso, reintenta con tanta fuerza que desencadena más limitaciones y gira en un bucle que agota tu presupuesto. La pregunta más frecuente en el foro de discusión del SDK de Anthropic es literalmente sobre patrones para la recuperación de errores de agentes, lo que te dice cuán común es este problema.
No puedes probar la recuperación contra una API saludable, porque una API saludable nunca devuelve los errores que necesitas manejar. Aquí es donde la simulación demuestra su valor. Configura una simulación de la dependencia del agente y programa una secuencia: un 429 con un encabezado `Retry-After`, luego un 500, luego un éxito. Ahora observa lo que hace tu agente. ¿Retrocede con fluctuación? ¿Respeta el encabezado? ¿Se rinde graciosamente después de un número sensato de intentos, o abre un disyuntor para dejar de sobrecargar un servicio que claramente está caído? Y si una acción reintentada no es idempotente, ¿un reintento duplica el cargo o el envío? Una clave de idempotencia es lo que hace que un reintento sea seguro de repetir.
Los límites de tasa merecen su propio ensayo. Si no has visto cómo se comporta tu agente cuando un proveedor lo limita, lee nuestra guía sobre lo que significa una respuesta de límite de tasa excedido y luego simúlalo. La guía dedicada sobre recuperación de errores de agentes de IA cubre completamente los patrones de reintento, tiempo de espera, retroceso exponencial y disyuntor.
Modo de fallo 3: Salida no determinista
Aunque pongas la temperatura a cero, no obtendrás una salida byte a byte idéntica entre ejecuciones. Los desarrolladores redescubren esto constantemente; hay un largo hilo de vLLM sobre cómo las semillas y la temperatura no son suficientes para la reproducibilidad. El hardware, el procesamiento por lotes y los cambios por parte del proveedor introducen variaciones. Si tus pruebas afirman cadenas exactas, se vuelven inestables, y las pruebas inestables se ignoran, lo cual es peor que no tener pruebas. Nuestro resumen de lo que causa las pruebas inestables se aplica directamente aquí.
La solución es afirmar la estructura y el significado, no el texto exacto. Comprueba que la respuesta se valida contra un esquema JSON. Comprueba que la llamada a la herramienta tiene la forma correcta y el objetivo correcto. Comprueba que una respuesta numérica cae dentro de un rango sensible. Comprueba que existen las claves requeridas y que los campos prohibidos están ausentes. Una prueba que dice "la respuesta contiene un `total` entre 0 y el valor del carrito" sobrevive a la variación natural del modelo mientras sigue detectando una regresión real. La guía sobre cómo probar agentes de IA no deterministas expone el conjunto completo de estrategias, y el artículo sobre cómo funciona la memoria del agente muestra por qué el estado lo hace más difícil.
Modo de fallo 4: Costo descontrolado
Los agentes entran en bucle, y los bucles cuestan dinero. Un solo agente atascado que reintenta una llamada fallida unas pocas miles de veces puede convertir una factura pequeña en una grande de la noche a la mañana. Un informe de campo en las discusiones del SDK describió cómo se redujo el costo de un agente de 500 dólares al mes a 80 sin perder calidad, lo que demuestra tanto lo rápido que se dispara el costo como la cantidad de margen que suele ocultarse en el diseño.
El costo es un problema de fiabilidad, no solo financiero, porque los errores que desperdician dinero (bucles, llamadas redundantes, contexto sobredimensionado) también hacen que el agente sea lento e impredecible. Rastrea los tokens por ejecución, limita el presupuesto por tarea y almacena en caché lo que puedas. Para la parte de línea de comandos de esto, nuestra guía sobre cómo reducir los costos de tokens del agente tiene palancas concretas. Cuando pruebes rutas de recuperación contra una simulación, también observa el recuento de llamadas. Un agente que tiene éxito pero realiza cuarenta llamadas para lograrlo es un incidente de costo esperando a ocurrir.
Modo de fallo 5: Ausencia de barandillas de seguridad
Los fallos que más duelen son aquellos en los que el agente hace exactamente lo que se le dijo y el resultado sigue siendo malo. Envía el correo electrónico, elimina el registro o realiza el pedido, porque nada se interpuso entre la decisión del modelo y la acción en vivo. Los foros del SDK tienen un hilo memorable construido alrededor de un agente que envió un correo electrónico a las tres de la mañana al jefe de alguien. Divertido una vez, caro dos veces.
Las barandillas de seguridad son el cinturón de seguridad. Pon una lista de acciones permitidas en las acciones que un agente puede tomar sin aprobación. Protege las llamadas destructivas o irreversibles con una confirmación humana. Dale al agente un modo de ejecución en seco que describa lo que haría sin hacerlo. Luego, prueba que la barandilla de seguridad se mantiene: simula el endpoint con efectos secundarios, ejecuta el agente y afirma que entra en la ruta de confirmación en lugar de la acción en vivo. La guía de seguridad como la OWASP Top 10 para aplicaciones de modelos de lenguaje grandes es una lista de verificación sólida para lo que hay que proteger. La guía sobre barandillas de seguridad para agentes de IA cubre en profundidad las puertas de aprobación y el control del radio de explosión.
Cómo estructurar una prueba de agente
Los cinco modos comparten una forma de prueba, y puedes reutilizarla:
- Captura los esquemas de herramientas que tu agente puede llamar, para que tengas un contrato contra el cual afirmar.
- Simula cada dependencia para controlar la temporización, los códigos de estado y los cuerpos, y para evitar efectos secundarios reales.
- Dirige al agente a través del escenario, incluidas las rutas infelices que una API en vivo no producirá bajo demanda.
- Afirma lo que el agente envió y cómo reaccionó: forma de la solicitud, comportamiento de recuperación, número de llamadas y si las barandillas de seguridad se activaron.
Ejecuta ese bucle para una herramienta, luego añade la siguiente. La configuración se amortiza la primera vez que detecta una llamada a una herramienta rota antes de que lo haga un usuario.
La lista de verificación de fiabilidad del agente
Antes de que un agente pase a producción, revisa esta lista:
- Cada llamada a una herramienta se valida contra un esquema, y las violaciones de contrato fallan una prueba.
- Las respuestas de 429, 500 y tiempo de espera de los sistemas ascendentes se simulan, y el agente se recupera con retroceso exponencial.
- Las acciones reintentadas son idempotentes, de modo que una repetición no puede duplicar el cargo o el envío.
- Las pruebas afirman la estructura y el significado, no las cadenas exactas, para que la variación normal no cause inestabilidad.
- Se mide el uso de tokens por ejecución, y un límite de presupuesto detiene los bucles descontrolados.
- Las acciones destructivas están detrás de una lista blanca o una puerta de aprobación humana.
- La ruta de la barandilla de seguridad se prueba con una simulación, no se asume.
Marca las siete y habrás probado las formas en que los agentes fallan en producción.
Dónde encaja Apidog (y dónde no)
Sé claro sobre el trabajo de la herramienta. Apidog no es un framework de agente, un host de modelos o un arnés de evaluación. No construye ni ejecuta tu agente. Lo que hace es controlar la capa de API de la que depende tu agente, que es exactamente donde viven estos fallos.
En la práctica, esto significa tres cosas. Diseñas y almacenas los contratos para las herramientas que llama tu agente, para que puedas validar las solicitudes salientes contra ellos. Simulas esas dependencias y programas las respuestas de fallo (429, 500, tiempo de espera, cuerpo mal formado) que una API en vivo no producirá bajo demanda, para que puedas ensayar la recuperación. Y escribes afirmaciones sobre las respuestas (esquema, forma, rangos, claves requeridas) que sobreviven a la salida no determinista. Ese es el ajuste honesto: Apidog prueba las APIs que llama tu agente, simula los fallos que necesitas manejar y verifica lo que se devuelve. Nuestra descripción general de pruebas de IA agéntica sitúa esto en el panorama más amplio de control de calidad.
Preguntas frecuentes
¿Es la fiabilidad del agente un problema del modelo o un problema de ingeniería? Principalmente ingeniería. La elección del modelo importa, pero los fallos que causan incidentes (llamadas a herramientas erróneas, límites de tasa no gestionados, barandillas de seguridad ausentes) son problemas de integración y pruebas que puedes resolver sin cambiar el modelo.
¿Puedo probar un agente sin acceder a las APIs reales a las que llama? Sí, y deberías. Simula las dependencias para poder forzar respuestas de error, controlar los tiempos y evitar efectos secundarios. Esa es la única forma fiable de probar las rutas de recuperación y las barandillas de seguridad.
¿Cómo escribo pruebas cuando la salida cambia en cada ejecución? Afirma la estructura y el significado en lugar del texto exacto. Valida la respuesta contra un esquema, verifica la forma de la llamada a la herramienta y usa rangos para los números. La guía cómo probar agentes de IA no deterministas cubre esto en detalle.
¿Qué debo probar primero? Las barandillas de seguridad en acciones destructivas, luego la recuperación de errores. Esos dos te protegen de los fallos más costosos: un agente que realiza una acción dañina, o un agente que entra en bucle y agota tu presupuesto.
Empieza con un modo de fallo
No tienes que probar los cinco modos a la vez. Elige el que más te asuste, normalmente las barandillas de seguridad o la recuperación de errores, y ensáyalo contra una simulación esta semana. Programa el fallo, ejecuta el agente y observa lo que hace. La primera vez que veas a tu agente manejar un 429 simulado con un retroceso limpio en lugar de un bucle que agota el presupuesto, confiarás más en él, y por una razón mejor que una demo verde.
Descarga Apidog para diseñar los contratos, simular los fallos y afirmar las respuestas de las que depende tu agente.