De la demo al entorno real: cómo estructurar flujos con LangGraph para evitar alucinaciones en producción

Casi cualquier desarrollador puede construir una demo de agente con IA en un fin de semana utilizando un bucle ReAct estándar: le das al modelo un conjunto de herramientas, un prompt con instrucciones y dejas que decida autónomamente qué ejecutar en cada iteración.

En una presentación interna de PowerPoint, esto parece revolucionario. Pero en cuanto conectas ese agente a un proceso de negocio real con consecuencias financieras (como evaluar el siniestro de un vehículo, aprobar un reembolso o emitir un presupuesto legal), el sistema colapsa rápidamente:

• El agente entra en bucles infinitos llamando a herramientas redundantes.
• Modifica datos previos que ya habían sido verificados.
• Inventa parámetros no contemplados en la API de destino.
• El coste en tokens se dispara sin correlación con el resultado.

En este artículo explico la arquitectura que utilizamos en PeritIA para transformar un problema de visión artificial y peritaje de automóviles en un sistema determinista, auditable y con cobertura de tests exhaustiva.

Por qué los agentes libres fallan en producción

El problema de fondo radica en dar al modelo el control completo del flujo de control (control flow).

En software tradicional, el flujo lo determinan las reglas de negocio y los estados de la aplicación. En un agente sin restricciones, el flujo depende de la probabilidad estadística de que el modelo decida llamar a la herramienta correcta en el momento adecuado. Si esa probabilidad es del 95% por paso, tras seis decisiones encadenadas la fiabilidad total cae por debajo del 74%.

Para entornos de producción, la solución consiste en invertir la ecuación: el código gobierna el flujo de estados y la IA resuelve únicamente tareas cognitivas acotadas dentro de cada nodo.

La arquitectura StateGraph de 5 nodos

En lugar de un bucle abierto, estructuramos el proceso como un grafo acíclico dirigido con memoria tipada compartida mediante LangGraph:

[Fotografías del Siniestro]
            │
            ▼
 ┌─────────────────────┐
 │ 1. Identificación   │ ──► Valida marca y modelo del vehículo
 └──────────┬──────────┘
            │
            ▼
 ┌─────────────────────┐
 │ 2. Detección Daños  │ ──► Segmentación visual de piezas y golpes
 └──────────┬──────────┘
            │
            ▼
 ┌─────────────────────┐
 │ 3. Mapeo de Piezas  │ ──► Cruce vectorial local (pgvector + fastembed)
 └──────────┬──────────┘
            │
            ▼
 ┌─────────────────────┐
 │ 4. Reglas de Coste  │ ──► Consulta determinista en grafo Neo4j
 └──────────┬──────────┘
            │
            ▼
  < ¿Coste > 70% Valor Venal? >
        │               │
      [Sí]             [No]
        │               │
        ▼               ▼
 [Siniestro Total]  [Propuesta Reparación]

Nodo 1: Identificación y Calidad de Imagen

Comprueba si las fotografías aportadas tienen suficiente resolución e identifican el vehículo correcto. Si una imagen está borrosa o no corresponde al siniestro, el flujo se detiene de inmediato sin quemar tokens en pasos posteriores.

Nodo 2: Detección Multimodal de Daños

Aplica modelos de visión para clasificar piezas afectadas y severidad del impacto, restringiendo las etiquetas a un catálogo cerrado de piezas homologadas.

Nodo 3: Mapeo Vectorial Local

Para evitar enviar miles de páginas de catálogos de recambios a una API externa, cruzamos los términos detectados con una base vectorial local sobre pgvector usando fastembed. Cero coste de API en la búsqueda de piezas.

Nodo 4: Relaciones de Piezas y Mano de Obra en Neo4j

Sustituir un faro moderno requiere desmontar el paragolpes frontal. Esta regla de negocio no se le pide al modelo por prompt, sino que se consulta en una base de datos de grafos (Neo4j) que devuelve los tiempos de taller tasados y los pasos de taller asociados.

Nodo 5: Bifurcación Condicional

El nodo final compara el presupuesto acumulado con el valor venal del vehículo. Si supera el umbral del 70%, emite propuesta de siniestro total; si no, genera el desglose de reparación estructurado.

Cómo testear sistemas agénticos para dormir tranquilo

La mayor objeción al desplegar IA en procesos empresariales es la falta de reproducibilidad en los tests.

En este sistema, aplicamos una estrategia de pruebas en tres capas:

1. Validación de esquemas Pydantic: cada nodo tiene un contrato de entrada y salida inmutable. Si un modelo intenta devolver una clave no esperada, la ejecución falla antes de propagarse.
2. Tests unitarios deterministas con mocks: 142 pruebas en pytest que aíslan cada nodo del grafo, inyectando respuestas simuladas para comprobar transiciones de estado, bifurcaciones y límites de cálculo.
3. Evals de regresión con LangSmith: sobre un conjunto de 50 siniestros reales pre-etiquetados, medimos que los cambios en prompts o modelos no degraden la precisión por debajo de los umbrales de referencia.

Conclusión

La inteligencia artificial más valiosa en las empresas no es la que escribe poemas ni la que improvisa decisiones complejas sin supervisión. Es la que ejecuta tareas cognitivas específicas dentro de una jaula determinista construida con ingeniería de software rigurosa.

Si diseñas tus agentes como máquinas de estados finitos con contratos estrictos, transformarás una demo frágil en un activo operativo que ahorra horas de trabajo cada día.