Errores que se entienden

«Error 500» no le sirve a nadie

Imagina que pides un taxi y la app solo responde «Algo salió mal». No sabes si falta tu dirección, si no hay conductores o si se cayó el servicio. Pero si dice «No hay conductores cerca; prueba en 10 minutos», sabes qué hacer.

Para un agente es igual, con una diferencia: no puede llamar a soporte. Anthropic señala que los agentes dependen de recibir la verdad del terreno del entorno en cada paso, como los resultados de las herramientas, y de poder recuperarse de errores. Si el resultado de un fallo es opaco, el agente no puede corregirse.

Qué hace útil a un error

Un buen mensaje de error responde tres preguntas:

1. Qué pasó (en lenguaje claro).
2. Por qué, si se sabe.
3. Qué puede hacer ahora el agente.

Mal:  Error: failed
Bien: No se encontró "src/app.py". La ruta debe ser absoluta
      (por ejemplo /proyecto/src/app.py). Archivos cercanos: /proyecto/src/main.py

Este segundo mensaje casa con el principio poka-yoke de la lección anterior: no solo avisa, también guía hacia la forma correcta.

Reintentos con cabeza

Que el agente pueda reintentar es bueno, pero sin freno es un riesgo. La fuente recomienda condiciones de parada (como un máximo de iteraciones) y puntos de control donde pausar y pedir ayuda humana ante un bloqueo. Una pauta práctica derivada de ello:

• Reintenta cuando el error indica algo corregible (ruta mal escrita).
• Si el mismo error se repite varias veces, para y pide ayuda en vez de insistir.
• No reintentes a ciegas acciones con efectos (como borrar o pagar) sin comprobar el estado antes.

Esto último conecta con la advertencia de la skill harness-creator: las herramientas con efectos no deben tratarse como las de solo lectura (más en permisos y límites).