Gestión de errores de herramientas y resultados parciales en un bucle de agente

Qué es

Tres desenlaces requieren tres resultados distintos. Un error de protocolo (herramienta desconocida, argumentos no válidos, servidor inaccesible) es un fallo de la propia llamada; el Model Context Protocol lo notifica como error JSON-RPC. Un error de ejecución de la herramienta (la API upstream devolvió 500, el archivo no existe, la consulta superó el tiempo de espera) es un resultado válido que indica que la operación falló; MCP lo devuelve dentro del resultado con isError: true, y la documentación de uso de herramientas del proveedor describe el indicador equivalente is_error: true en un bloque tool_result, tras lo cual el modelo incorpora el error en su siguiente paso. Un resultado parcial (7 de 10 archivos procesados, la primera página de una búsqueda, un lote con dos filas rechazadas) es un éxito cuyo contenido debe indicar qué falta.

Por qué importa

Un agente actúa según lo que dice el resultado de la herramienta. Una excepción que nunca llega al modelo produce una respuesta segura de sí misma, pero construida sobre nada. Un error sin detalle produce reintentos a ciegas de la misma llamada. Un resultado parcial presentado como completo produce una tarea marcada como terminada con filas perdidas en silencio.

Cómo aplicarlo

• Nunca dejes que una excepción escape de la herramienta; captúrala y devuelve un resultado de error con un tipo de error estable, el mensaje y, cuando se sepa, si un reintento puede ayudar (no en un 404, sí en un timeout).
• En los resultados parciales, devuelve la parte correcta junto con una lista explícita de lo que falló y por qué, y un cursor o identificador para continuar.
• Mantén el texto de error breve y factual; sin trazas de pila ni salidas del servicio upstream que puedan contener instrucciones inyectadas.
• Aplica los límites de reintentos en el bucle, no mediante instrucciones: se permite repetir un número fijo de veces la misma herramienta con los mismos argumentos tras un error; después, el bucle devuelve el control con un resumen.
• Haz que las herramientas de escritura sean idempotentes o dales una clave de idempotencia, de modo que un reintento tras un fallo ambiguo no duplique el efecto.
• Distingue entre "sin resultados" y "error": una búsqueda vacía es un resultado válido y completo.
• Registra cada resultado de error con el ID de ejecución; el patrón de errores es el informe de usabilidad de la herramienta.

Trampas

Devolver null o una cadena vacía ante un fallo. Reducir todos los fallos a un único mensaje genérico. Dejar que el modelo decida cuántas veces reintentar. Lanzar un error de protocolo por una condición de negocio ("pedido no encontrado" es un resultado, no una llamada mal formada). Mostrar los resultados parciales solo en un log que el modelo nunca ve.