Lección 1: Por qué no puedes decir qué salió mal

Objetivos de aprendizaje:

• Entender por qué un solo síntoma visible para el usuario puede esconder varias causas raíz indistinguibles entre sí
• Explicar cómo el no determinismo rompe la intuición tradicional de depuración «reprodúcelo y pon un punto de interrupción»
• Reconocer las distintas formas que toman los errores en sistemas de agentes: fallos en cascada, divergencia de trayectoria, acumulación entre turnos y emergencia multiagente

Requisitos: Completar los primeros 10 cursos de esta serie, poder escribir a mano un bucle de arnés gobernado por stop_reason, entender que la vía de evaluación solo te da aprobado/fallido | Siguiente: Lección 2 >>

Un martes por la tarde que no puedes explicar

Tu agente de investigación interno lleva dos semanas en producción. El martes por la tarde, el equipo de operaciones te reenvía un reporte de un usuario:

Le pedí que buscara nuestro plan de precios del año pasado. Dijo que no encontraba nada. Pero ese documento está ahí mismo, en la base de conocimiento — a mí me tomó dos segundos abrirlo.

Abres la sesión. Dos cosas en pantalla: la pregunta del usuario y la respuesta final del agente, «No encontré materiales relevantes». ¿Qué pasó en medio? No tienes nada.

Así que empiezas a adivinar.

¿Construyó una mala consulta de búsqueda — por ejemplo, tomar la pregunta del usuario en lenguaje natural y meterla entera y literal en la recuperación en lugar de extraer palabras clave? ¿O quizá encontró resultados pero eligió las fuentes equivocadas, leyendo los dos resultados menos relevantes de ocho y concluyendo «aquí no hay nada»? ¿O la herramienta de recuperación lanzó un error, y el agente interpretó el fallo como «no hay información en esta dirección» y siguió de largo?

Las tres conjeturas se ven idénticas desde el lado del usuario: el agente no puede encontrar información que está obviamente ahí.

Esto no te pasa solo a ti. Cuando el equipo de Anthropic hizo una retrospectiva de su sistema multiagente de investigación, anotaron exactamente el mismo problema: los usuarios reportaban que los agentes «no encontraban información obvia», pero ellos no podían ver por qué. ¿Los agentes estaban usando malas consultas de búsqueda? ¿Eligiendo fuentes pobres? ¿Topándose con fallos de herramientas?¹ Las mismas tres preguntas, sin respuestas.

La vía de evaluación solo responde «¿se rompió?»

Tu primer instinto probablemente sea abrir el sistema que construiste en el curso anterior (el Curso 10 de esta serie): calificación del estado final, validadores, conjuntos de evaluación. Ese es el primer paso correcto. Agregas esta pregunta real del usuario al conjunto de evaluación, escribes un criterio «la respuesta debe citar el documento de precios» y lo ejecutas.

Resultado: una línea roja. fail.

Esa línea roja sirve — convierte una queja subjetiva en un veredicto reproducible y testeable frente a regresiones. Pero no responde la pregunta que de verdad necesitas responder ahora mismo: por qué. El calificador mira el estado final. El estado final es «no citó el documento». Si ese «no citó» vino de una mala consulta, de la selección de fuentes o de un error de herramienta que se tragó — al calificador no le importa ni tiene manera de que le importe. Se queda en la meta levantando una tarjeta de puntuación.

Este curso llena la parte del medio. Con un marco que este curso acuñó:

La verificación te dice si se rompió. La observabilidad te dice por qué.

Esta no es una frase de ninguna documentación oficial — es el encuadre de este curso para amarrar las siguientes cinco lecciones, respaldado por dos experiencias reales. Una viene de esa retrospectiva del sistema multiagente: agregar trazado completo en producción les permitió diagnosticar por qué fallaban los agentes y arreglar los problemas de forma sistemática¹. La otra viene del lado de la ingeniería de herramientas: analizar las transcripciones crudas que deja tu agente de evaluación puede ayudarte a sondear por qué los agentes llaman o no llaman ciertas herramientas². Ambas frases apuntan a lo mismo — solo cuando el proceso deja un rastro puedes preguntar «por qué».

Por qué «reprodúcelo y pon un punto de interrupción» no funciona aquí

Primero, definiciones. Un sistema determinista significa: dale la misma entrada y produce la misma salida cada vez. Un sistema no determinista es lo contrario — los agentes son sistemas de este tipo. En computación, los sistemas deterministas producen la misma salida cada vez ante entradas idénticas, mientras que los sistemas no deterministas —como los agentes— pueden generar respuestas variadas incluso con las mismas condiciones iniciales².

Esto le quita el piso a la depuración tradicional. Los agentes toman decisiones dinámicas y son no deterministas entre ejecuciones, incluso con prompts idénticos. Eso hace más difícil depurarlos¹. Las evaluaciones tradicionales suelen asumir que la IA sigue los mismos pasos cada vez: dada la entrada X, el sistema debería seguir el camino Y para producir la salida Z. Pero los sistemas multiagente no funcionan así. Incluso con puntos de partida idénticos, los agentes podrían tomar caminos válidos completamente diferentes para llegar a su meta¹.

Así se ve en la práctica:

Misma pregunta, misma versión del prompt, dos ejecuciones
Ejecución A                                   Ejecución B1 search("plan de precios 2024")              1 search("plan de precios 2024 docs internos")2 read_doc(doc_17)                            2 search("archivo de precios")3 respond (cita doc_17)                       3 read_doc(doc_09)                                              4 read_doc(doc_17)                                              5 respond (cita doc_17 y doc_09)

Ninguno de los dos caminos está mal, y ambos estados finales pasarían. Pero si el fallo ocurrió en el paso 2 de la Ejecución A, y vuelves a ejecutar diez veces y obtienes nueve Ejecuciones B, esas nueve ejecuciones no te sirven.

Los puntos de interrupción son igual de inútiles. Un punto de interrupción se para sobre una línea de código, con la condición previa de que «la segunda ejecución llegará a esta línea con el mismo contexto». Pero donde los agentes se equivocan a menudo no es en tu código — es en una decisión del modelo. Y aunque quisieras pausar, no sabrías en qué turno pausar: esta vez se rompe en el turno 3, la próxima vez quizá en el turno 11, o quizá no se rompa nada.

Podrías pensar en bajar la temperatura de muestreo o en grabar y reproducir las respuestas de herramienta. Estas técnicas de ingeniería sí reducen algo del ruido, y este curso no te desalienta de usarlas. Pero cambian la ejecución que estás haciendo en tu laboratorio, no la que ya falló en producción — esa se fue, y lo único que dejó atrás son sus registros.

El equipo de Anthropic tomó un camino distinto. Lo llaman «pensar como tus agentes»: construir una simulación usando exactamente los mismos prompts y herramientas del sistema, y después observar a los agentes trabajar paso a paso. Esto reveló de inmediato modos de fallo: agentes que seguían adelante cuando ya tenían resultados suficientes, que usaban consultas de búsqueda demasiado verbosas o que seleccionaban herramientas incorrectas¹.

La clave no es «reproducir la misma ejecución» — es «ver cada paso». Ahí es donde la observabilidad se separa de la depuración tradicional.

Los errores que lanzan los agentes vienen en distintas formas

Aunque aceptes que «necesitas registros», hay otra capa por entender: la forma de los errores en sistemas de agentes no es la misma que la de los bugs tradicionales.

En el software tradicional, un bug podría romper una funcionalidad, degradar el rendimiento o provocar caídas. En los sistemas agénticos, cambios menores se propagan en cascada hasta convertirse en cambios grandes de comportamiento, lo que hace notablemente difícil escribir código para agentes complejos que deben mantener estado en un proceso de larga duración¹.

Dentro de una sola ejecución, la forma más típica es la divergencia de trayectoria. Los agentes tienen estado y los errores se acumulan. La naturaleza acumulativa de los errores en sistemas agénticos significa que problemas menores para el software tradicional pueden descarrilar por completo a los agentes. Que un paso falle puede hacer que los agentes exploren trayectorias completamente distintas, llevando a resultados impredecibles¹.

Turno 3: la búsqueda expira, la herramienta devuelve "Error: upstream timeout"         ↓El agente lo lee como "no hay información en esta dirección"         ↓Cambia a un ángulo de recuperación completamente distinto         ↓Los siguientes 12 turnos crecen todos sobre esta rama equivocada         ↓Estado final: un informe aparentemente completo, todas las fuentes de material tangencial

Fíjate en lo pequeño que es el primer eslabón de esa cadena: un solo timeout. En un servicio tradicional podría ser apenas una línea de log de reintento. Aquí reescribe los siguientes doce turnos, y el informe del estado final no da error, no se cae, se lee perfectamente fluido.

La segunda forma es la acumulación entre turnos. Los agentes tienen estado y los errores se acumulan. Los agentes pueden ejecutarse durante períodos largos, manteniendo estado a lo largo de muchas llamadas a herramientas. Esto significa que necesitamos ejecutar código de forma durable y manejar los errores en el camino¹. Por eso tampoco puedes simplemente reiniciar desde el principio cuando ocurren errores: los reinicios son caros y frustrantes para los usuarios. En su lugar, construyeron sistemas que pueden reanudar desde donde estaba el agente cuando ocurrieron los errores¹. La implicación para ti es directa: si el estado al momento del fallo no quedó registrado, la pregunta «desde dónde reanudar» no tiene respuesta.

La tercera forma solo aparece en sistemas multiagente: el comportamiento emergente. Los sistemas multiagente tienen comportamientos emergentes, que surgen sin haber sido programados específicamente. Por ejemplo, cambios pequeños en el agente líder pueden cambiar de forma impredecible cómo se comportan los subagentes. El éxito requiere entender los patrones de interacción, no solo el comportamiento de agentes individuales¹.

Sobre cómo se ven estas formas cuando convergen todas, la versión temprana de ese equipo dio una respuesta muy directa: los agentes tempranos cometían errores como lanzar 50 subagentes para consultas simples, rastrear la web sin parar buscando fuentes inexistentes y distraerse entre sí con actualizaciones excesivas¹.

Estos tres tipos de error tienen algo en común: vistos desde afuera, el estado final podría verse simplemente como «la calidad de la respuesta está regular». No puedes distinguir cuál de los tres es.

Las capas de abstracción esconden la evidencia

Hay otra capa de problema, y no viene del modelo — viene de tus herramientas.

Los frameworks de agentes facilitan arrancar porque simplifican tareas estándar de bajo nivel como llamar a los LLM, definir y parsear herramientas y encadenar llamadas. Sin embargo, a menudo crean capas extra de abstracción que pueden ocultar los prompts y las respuestas subyacentes, haciéndolos más difíciles de depurar³. Por eso el consejo a los desarrolladores es: empieza usando las API de LLM directamente — muchos patrones se pueden implementar en unas pocas líneas de código. Si usas un framework, asegúrate de entender el código subyacente. Las suposiciones incorrectas sobre lo que hay debajo del capó son una fuente común de error del cliente³. (Ese artículo incluye una nota editorial que dice que su descripción del ecosistema de herramientas está desactualizada, así que aquí citamos los principios, no lo tratamos como guía vigente de selección.)

Para ti, esto en realidad es una buena noticia. Escribiste a mano el bucle del arnés en el Curso 7 de esta serie. No tienes esa capa de abstracción:

La evidencia fluye por este bucle cada vez, sin falta. El problema es que después de fluir, se fue. No tienes obstrucción, pero tampoco tienes retención — desde la perspectiva de pedir evidencia después del hecho, esas dos cosas duelen igual.

Así que el diagnóstico de este curso es: la mitad de la dificultad de depurar agentes viene del hecho objetivo del no determinismo, y la otra mitad viene de que «cosas que se podían haber registrado no se registraron». La primera mitad no se puede cambiar. La segunda está en tus manos.

El camino adelante: qué te dan las siguientes cinco lecciones

El equipo de ese sistema multiagente puso esto al mismo nivel que la ingeniería de prompts y el diseño de herramientas: lograrlo bien depende de un prompting y un diseño de herramientas cuidadosos, heurísticas sólidas, observabilidad y ciclos de retroalimentación estrechos¹. La retrospectiva tiene una frase todavía más directa — se enfocaron en un ciclo de iteración rápido con observabilidad y casos de prueba¹.

Fíjate en la mitad de «casos de prueba»: la observabilidad no viene a reemplazar la vía de evaluación. Son los dos extremos de la misma vara de carga. La evaluación te dice si esta ejecución se rompió y si el cambio mejoró las cosas. La observación te dice por qué se rompió esta ejecución y qué parte cambiar.

Las siguientes cinco lecciones avanzan en este orden:

• La Lección 2 pone los cimientos: los registros crudos son la evidencia de primera mano. Lo que el agente dice sobre sí mismo no cuenta — lo que omite suele ser más importante que lo que incluye.
• La Lección 3 convierte cada paso en datos: logs estructurados y métricas. Las mismas métricas que el Curso 10 usó para calificar, este curso las usa para diagnosticar.
• La Lección 4 hilvana los registros dispersos en un árbol: leer como una sola unidad todas las solicitudes al modelo y ejecuciones de herramienta que disparó un prompt, con las llamadas a subagentes anidadas dentro del padre.
• La Lección 5 instala sondas en los puntos de control del ciclo de vida del bucle y recorre el flujo de localizar-bajo-no-determinismo: encontrar la primera divergencia dentro de un montón de registros.
• La Lección 6 es práctica: instalar una capa de observabilidad completa sobre el arnés que escribiste en el Curso 7, y trazar desde un síntoma que «no puedes explicar» hasta el paso específico que divergió.

Esta lección solo los nombra sin desarrollarlos: cómo leer registros es trabajo de la Lección 2, cómo diseñar métricas es de la Lección 3, qué estructura tiene una traza es de la Lección 4.

Cuándo no necesitas el stack completo

No todos los agentes necesitan todo esto. Un script de una sola vez —lo ejecutas una vez, le echas un ojo a la salida, lo borras— darle logs, métricas y trazas es puro desperdicio.

El criterio de juicio es simple: la inversión en observabilidad debería ser proporcional a «cuánto te tomaría explicar por qué después de que algo se rompa». Si lo ejecutas tú, lo miras tú, y no cuesta nada volver a ejecutarlo cuando falla, no registres. Si lo usa alguien más, si se ejecuta largo, si gastarías medio día escarbando transcripciones de chat cuando falle, registra desde el día uno.

Hay una línea que no tiene nada que ver con la escala: si el agente puede tomar acciones —escribir archivos, enviar solicitudes, gastar dinero— no te saltes las pruebas. La naturaleza autónoma de los agentes implica costos más altos y potencial de errores acumulativos. Recomendamos pruebas extensivas en entornos aislados, junto con los guardrails apropiados³.

En cuanto a saber si lo hiciste bien: la clave del éxito, como con cualquier funcionalidad de LLM, es medir el rendimiento e iterar sobre las implementaciones³. Y la condición previa para medir es tener algo que medir — lo cual vuelve al problema que este curso resuelve.

💻 Ejercicios

Resumen

• Un solo síntoma visible para el usuario suele esconder varias causas completamente indistinguibles desde afuera. Cuando los usuarios reportan que los agentes «no encuentran información obvia», no puedes distinguir si son malas consultas de búsqueda, mala selección de fuentes o fallos de herramientas¹.
• La vía de evaluación responde «¿se rompió?». Este curso usa un encuadre que acuñó para aclarar la división del trabajo: la verificación te dice si se rompió, la observabilidad te dice por qué. Lo respaldan dos experiencias reales — agregar trazado completo en producción les permitió diagnosticar fallos y arreglar de forma sistemática¹, y leer transcripciones crudas puede ayudarte a sondear por qué los agentes llaman o no llaman ciertas herramientas².
• «Reproducir y poner un punto de interrupción» falla porque los agentes toman decisiones dinámicas y son no deterministas entre ejecuciones, incluso con prompts idénticos¹. Los sistemas deterministas dan la misma salida ante la misma entrada; los agentes, como sistemas no deterministas, no lo garantizan². La suposición de la evaluación tradicional —«la entrada X sigue el camino Y y produce la salida Z»— tampoco se sostiene. Puntos de partida idénticos pueden producir caminos válidos completamente diferentes¹.
• Las formas de error de los agentes difieren de los bugs tradicionales: en el software tradicional los bugs rompen una funcionalidad, pero en los sistemas agénticos los cambios menores se propagan en cascada hasta convertirse en cambios grandes de comportamiento, lo que hace notablemente difícil escribir código para agentes complejos que deben mantener estado¹. Que un paso falle puede hacer que los agentes exploren trayectorias completamente distintas, llevando a resultados impredecibles¹. Los agentes tienen estado y los errores se acumulan, así que necesitas ejecutar de forma durable y manejar los errores en el camino¹. Los sistemas multiagente además tienen comportamientos emergentes — cambios pequeños en el agente líder pueden cambiar de forma impredecible el comportamiento de los subagentes; lo que necesitas entender son los patrones de interacción, no solo los individuos¹. La versión temprana llegó a lanzar 50 subagentes para consultas simples, a rastrear la web sin parar buscando fuentes inexistentes y a distraerse entre sí con actualizaciones excesivas¹.
• Las capas de abstracción esconden la evidencia: los frameworks a menudo crean capas extra de abstracción que pueden ocultar los prompts y las respuestas subyacentes, haciéndolos más difíciles de depurar³. El consejo es empezar con las API de LLM directamente y, si usas un framework, entender el código de abajo³. Tu arnés escrito a mano no tiene obstrucción, pero tampoco retención.
• El camino adelante es tratar la observabilidad y los ciclos de retroalimentación estrechos como requisitos de primer nivel¹, integrados en un ciclo de iteración rápido con observabilidad y casos de prueba¹. Las siguientes cinco lecciones en secuencia: registros crudos, logs y métricas, trazas, hooks y flujo de localización, instalación práctica.
• Juicio sobre el alcance: los scripts de una sola vez no necesitan el stack completo. Pero si el agente puede tomar acciones, haz pruebas extensivas en entornos aislados con los guardrails apropiados³. Saber si lo hiciste bien depende de medir el rendimiento e iterar sobre las implementaciones³.

Lección 2 >>