Errores estructurados: cómo devolver fallas que el agente pueda resolver

Hola otra vez, y bienvenidos y bienvenidas a la cápsula dos del Módulo dos. Recuerda que esta es mi voz, pero el audio fue generado con inteligencia artificial, bajo la supervisión del equipo de EvoAcademy.

Hoy vemos el task statement dos punto dos: implementar respuestas de error estructuradas para herramientas MCP. MCP es el protocolo que conecta las herramientas con el modelo.

Cuando una herramienta MCP falla, el resultado se marca con el campo is error en verdadero, y así el agente sabe que la llamada no funcionó. Pero ese campo solo no alcanza: el agente necesita saber qué tipo de falla fue para decidir qué hacer. La guía distingue cuatro tipos. Si el error es transitorio, como un timeout, que es un tiempo de espera agotado, o un servicio no disponible, entonces se puede reintentar. Por su parte, si el error es de validación, porque el dato de entrada era inválido, entonces hay que corregirlo antes de reenviar. Además, si el error es de negocio, porque se violó una política, entonces no se reintenta. Y si el error es de permiso, porque no hay acceso, entonces tampoco se reintenta.

Una respuesta uniforme como Operation failed deja al agente a ciegas: puede reintentar algo que nunca va a funcionar, o rendirse ante algo pasajero. Por eso la guía pide metadatos estructurados: el campo error category, un booleano llamado is retryable, que indica si se puede reintentar, y una descripción legible. Para los errores de negocio se marca además que no son reintentables y se incluye una explicación amable para el cliente.

La especificación de MCP dice que los errores de ejecución de una herramienta se devuelven en el resultado con is error en verdadero, y que los clientes deberían pasarlos al modelo para que se corrija. Los campos error category e is retryable son una convención de la guía, no de la especificación.

La segunda mitad trata de dónde se maneja el error. En un sistema con un orquestador, que reparte el trabajo, y subagentes, que ejecutan tareas con un rol propio, el subagente resuelve por su cuenta las fallas transitorias, por ejemplo con un reintento acotado. Al orquestador solo sube lo que no pudo resolver, y sube con contexto: qué tipo de falla fue, qué se intentó y qué resultados parciales hay.

Una pregunta. Una búsqueda se ejecutó sin problemas y devolvió cero coincidencias. ¿Es una falla de acceso o un resultado vacío válido?

Es un resultado vacío válido: un éxito con cero resultados. Una falla de acceso es una consulta que no se pudo ejecutar. Confundirlas duele en las dos direcciones. Si una falla se marca como vacío exitoso, el orquestador cree que no hay información y entrega un informe incompleto sin saberlo. Por su parte, si un vacío se marca como error, se reintenta una consulta que ya respondió.

Dos preguntas de práctica. Pregunta uno. Un agente de una empresa de transporte usa una herramienta schedule pickup. Cuando falla, siempre devuelve el texto Operation failed. Hay tres causas: el servicio de mapas se cayó un momento, un código postal venía con formato inválido, y una dirección queda fuera de cobertura según la política de la empresa. El agente reintenta todo. ¿Qué cambio resuelve mejor el problema? Opción A: reintento automático con espera creciente para cualquier falla. Opción B: devolver el error con is error en verdadero, una categoría, el campo is retryable y una descripción legible, y para la cobertura una explicación para el cliente. Opción C: pedir en el system prompt, las instrucciones fijas del modelo, que reintente máximo dos veces. Opción D: devolver un texto libre más largo, sin campos estructurados.

La correcta es B. Con la categoría y el campo de reintento, el agente reintenta solo lo transitorio, corrige el código postal y explica la zona sin cobertura. La A reintenta incluso lo que nunca va a funcionar. La C le pide al modelo que adivine el tipo de error. La D entrega más palabras, pero sin categoría ni campo de reintento no hay base para decidir.

Pregunta dos, de respuesta múltiple. Elige dos. En una cadena de supermercados, un orquestador de reposición delega en un subagente de inventario que consulta tres bodegas. Norte responde que no tiene stock. Centro responde con doce unidades. Sur agota el tiempo tres veces seguidas. Opción A: reportar la consulta a Norte como exitosa con cero resultados. Opción B: reintentar localmente el timeout de Sur con un tope y, si persiste, devolver al orquestador el tipo de falla, la consulta intentada y los resultados parciales. Opción C: devolver para Sur una lista vacía marcada como exitosa. Opción D: marcar la respuesta de Norte como error, para que se reintente. ¿Cuáles dos?

Las correctas son A y B. Norte sí respondió, así que cero stock es un éxito con cero resultados. Sur es una falla transitoria: se reintenta de forma acotada y, si sigue, sube con contexto y datos parciales. La C esconde la falla detrás de un éxito. La D reintenta una consulta que ya respondió.

Si te sirvió, sigue el podcast, dale cinco estrellas y activa las notificaciones. En la próxima cápsula vemos cómo repartir las herramientas entre agentes y el parámetro tool choice, que controla si el modelo debe llamar una herramienta. Nos escuchamos en la próxima cápsula de EvoAcademy.