Te despiertas con cinco informes de errores críticos un lunes por la mañana. Tu herramienta de monitoreo de revisiones ha hecho su trabajo. Detectó cada informe de error, cada reseña de una estrella llena de ira, cada "la aplicación se congela cuando pulso guardar". Sabes exactamente qué está roto. Lo que no sabes es dónde buscar.

Ese fue el muro con el que me topé tras construir mi primer pipeline. Monitoreaba las reseñas de la aplicación y los registros de errores entrantes sin problemas, clasificando cada comentario en cubos ordenados: errores, fallos o solicitudes de funciones. El tablero de control se veía saludable. El proceso de depuración real, no.

Saber que existe un error es solo el primer paso de un largo camino. Todavía tenía que abrir el IDE, usar grep en los módulos, cotejar los stack traces con el código actual y reconstruir la ruta de la falla en mi cabeza. Cuando los tickets se acumulan y el café aún está caliente, esa arqueología manual consume un tiempo que no tienes. Necesitaba que el pipeline hiciera más que solo señalar problemas. Necesitaba que los investigara.

Así que reconstruí el sistema con un único objetivo: tomar un informe de error bruto y devolver un diagnóstico validado. No un párrafo de reflexiones de un LLM. Un hallazgo estructurado que nombre el archivo, señale la línea, estime el riesgo y sugiera una solución. Así es como se logró.

Por qué la estructura vence a un registro de chat

Construí el agente de investigación con PydanticAI. La razón era sencilla. Cuando le pides a un modelo de lenguaje que razone sobre código, su salida por defecto es un flujo amigable de texto. Eso puede ayudar a un lector humano, pero es inútil para un script posterior. Necesitaba un contrato legible por máquina.

El agente devuelve un modelo de datos validado con cuatro campos específicos: la causa raíz, los archivos afectados, los cambios propuestos y una evaluación de la complejidad y el riesgo. Si al modelo le falta un campo o alucina una ruta de archivo, la validación falla y lo detecto inmediatamente. Ese rigor mantiene la integridad del pipeline.

Para realizar el verdadero trabajo de detective, el agente dispone de cuatro herramientas de solo lectura y nada más. Puede buscar código mediante grep, leer rangos de líneas específicos de un archivo, listar el contenido de un directorio y localizar símbolos como clases o funciones. "Solo lectura" es la parte importante. No quería un agente con acceso de escritura deambulando por mi repositorio a las 2 a.m. Primero entender, luego editar.

El mapa del repositorio: contexto antes que herramientas

La primera versión del agente era precisa pero extremadamente costosa. Consumía tokens como un turista dando vueltas en círculos. El modelo llamaba a list-dir, luego a grep, luego leía un archivo, luego volvía a llamar a list-dir, ensamblando lentamente un modelo mental de la estructura del proyecto, un costoso token a la vez.

La solución fue generar un mapa compacto del repositorio antes de que el agente comenzara. Este mapa es una visión general destilada del repositorio: archivos clave, sus funciones o clases principales y cómo se conectan los módulos principales. Piensa en ello como entregarle al agente un GPS en lugar de pedirle que descubra las carreteras por ensayo y error.

Con ese mapa en su ventana de contexto, el agente no desperdicia llamadas intentando averiguar si src/utils/parser.ts existe. Ya conoce el terreno. Se dirige directamente a la cresta donde se levanta el humo. Ese único cambio eliminó por completo la fase de deambulación.

El embudo de herramientas: forzando una conclusión

Incluso con un mapa, el agente podía vacilar. Encontraba un archivo sospechoso, luego dudaba de sí mismo, luego buscaba de nuevo, luego leía otro archivo, atrapado en un bucle interminable de "solo una comprobación más". Necesitaba una forma de forzar el impulso.

Implementé un embudo de herramientas de tres fases que restringe lo que el agente puede hacer a medida que progresa.

La fase uno es exploración. El agente tiene acceso total a las cuatro herramientas. Puede buscar, navegar y leer lo que necesite para replicar el error en su razonamiento.

La fase dos es inmersión profunda. Una vez que el agente ha identificado las posibles líneas de falla, pierde las herramientas de descubrimiento. Solo puede leer archivos. No más grep, no más listados de directorios. En esta etapa, debe estudiar el código que ya ha encontrado y construir su cadena de evidencia.

La fase tres es la salida. Todas las herramientas quedan bloqueadas. El agente ya no puede consultar la base de código. Tiene que sentarse y escribir el informe. Esto evita la espiral interminable de "déjame revisar una cosa más".

Ese embudo redujo el número promedio de llamadas a herramientas de más de cuarenta por análisis a aproximadamente diez. El agente se volvió más rápido, más económico y, paradójicamente, más seguro de sí mismo porque tenía que comprometerse con una conclusión.

Mantener el backend intercambiable

No quería dejar el sistema vinculado de forma rígida a un único proveedor de modelos. Utilizo diferentes motores según la tarea. A veces Claude Code, a veces Grok Build, a veces lo que sea más barato en ese momento. Para mantener la lógica central independiente del proveedor, dividí el trabajo en dos etapas.

La primera etapa es la exploración. El agente de programación, que puede ser cualquier modelo capaz, lee el mapa del repositorio, utiliza las herramientas y genera un informe en markdown sin procesar. Esta es la parte del pensamiento costoso.

La segunda etapa es la estructuración. Un LLM económico y rápido toma ese markdown y lo reformatea en el modelo estricto de Pydantic. Esta etapa requiere casi nada de razonamiento. Es solo extracción y formato, por lo que se ejecuta en hardware ligero.

Como la frontera es clara, puedo cambiar el backend sin tocar la lógica de validación. El informe en markdown actúa como un adaptador universal entre el cerebro exploratorio y la salida estructurada que realmente utilizo.

Lo que realmente funcionó

Esta configuración cambió la forma en que gestiono las incidencias entrantes. La capa de clasificación sigue separando los errores de las solicitudes de funciones, pero ahora la capa de análisis comienza inmediatamente después. Para cuando abro mi editor, ya tengo una ruta de archivo, un rango de líneas y un cambio propuesto esperándome. Sigo revisando todo manualmente. Esto es asistencia, no piloto automático. Pero la recopilación de contexto que solía