🕸️ Graph Engineering en la práctica
Ahora que sabes qué es un grafo y dónde se atasca el loop: cómo se construye uno de verdad. Nodo, arista y estado en un sistema de agentes; la diferencia entre el organigrama que permanece y el trabajo que avanza; y los modos de falla que solo existen porque construiste un grafo.
Qué observar: abrir en N y luego unir (fan-out/fan-in) es el movimiento que un loop simplemente no hace: solo avanza en fila india. Cada cuadro cian es un loop completo con contexto propio, no un paso dentro del mismo loop. Y la arista roja de vuelta es el detalle que transforma esto de un DAG bonito en un grafo con un ciclo real, y por eso necesita un límite de vueltas, como cualquier ciclo de la Ruta 2.
Mapa de la ruta
Contenido detallado
🧩 Nodos, aristas y estado
Las tres piezas de un grafo agéntico y lo que cambia cuando el nodo deja de ser una caja en un dibujo y se convierte en una invocación de agente con modelo, herramientas y permisos propios.
Un nodo puede ser un agente, una llamada a un modelo, un fragmento de código común o una decisión humana. No todos los nodos necesitan IA.
Un nodo de código determinista es más barato y confiable. Usar un modelo cuando un `if` lo resuelve es un desperdicio.
El nodo es la unidad mínima de trabajo del grafo. Combina nodos de código y nodos de agente según la necesidad real.
La arista es donde reside el enrutamiento: «si se aprueba, continúa; si se rechaza, vuelve». Una arista condicional es lo que diferencia un grafo de una cola.
Sin una arista condicional tienes una secuencia fija, no un grafo. La condición es lo que da flexibilidad real al sistema.
Arista = decisión. Nodo = trabajo. Separar estas dos responsabilidades es lo que hace que el grafo sea legible.
Qué pasa exactamente de un nodo a otro. Pasar toda la conversación anula la ventaja de tener un contexto limpio; pasar demasiado poco hace que el siguiente nodo trabaje a ciegas.
El estado es el contrato entre nodos. Ajustar su tamaño es lo que hace que el grafo entregue contexto realmente limpio.
Pasa lo suficiente para decidir, nunca el historial completo por reflejo. Es la base del state schema del módulo 4.3.
El modelo, las herramientas, los permisos, las instrucciones e incluso el presupuesto pueden ser diferentes por nodo. Un modelo caro en el paso difícil, uno barato en el fácil.
Usar una herramienta de escritura solo en el nodo que necesita escribir reduce el riesgo y el costo. La configuración por nodo es lo que hace que el grafo valga la pena.
Cada nodo es un miniagente configurable: modelo, herramientas, prompt y permisos propios, no un clon del vecino.
Un grafo de un solo nodo, con todas las herramientas y todas las instrucciones, ejecutándose hasta agotarse: eso es un loop reinventado, y la estructura no está haciendo nada.
Si no puedes darles configuraciones diferentes a dos nodos, probablemente no necesitabas dos nodos.
El grafo degenerado es el antipatrón más común de quienes «convierten» un loop en grafo solo de nombre.
Demasiado grande y el grafo no ayuda; demasiado pequeño y pagas una sobrecarga de coordinación por un trabajo trivial.
Regla práctica: un nodo por cambio de contexto, herramienta o responsabilidad. Eso evita los dos extremos.
La granularidad es una decisión de diseño, no una regla fija, pero hay una heurística sencilla que puede guiar la elección.
🏢 Grafo organizacional x grafo de trabajo
Dos grafos conviven en el mismo sistema: la organización estable de agentes y el trabajo efímero de hoy. Confundirlos es la causa más común de un sistema desordenado.
Agentes de larga duración con roles definidos (investigador, escritor, validador, publicador), responsables de un dominio, con memoria acumulada.
Y el organigrama de tu empresa, donde cada cuadro es un agente ejecutando un loop. Solo cambia cuando vuelves a hacer el deploy.
Org graph = estabilidad + identidad. Rol con nombre, memoria propia, responsable del dominio.
Efímero, montado para una solicitud específica y descartado después. Cambia en cada ejecución.
Confundir work graph con org graph hace que rediseñes toda la organización con cada tarea nueva: es incorrecto y costoso.
Org graph = quién existe. Work graph = qué se hace ahora. Son dos grafos, no uno solo.
El de seguridad se ocupa de la autenticación, los permisos y los logs; el de datos, del esquema y las migraciones; el de API, de los endpoints y los contratos; el de frontend, de los componentes y el estado. Los pedidos de una zona a otra pasan por el work graph.
Esto es lo que hace que un agente de larga vida acumule valor: un agente de seguridad que ya revisó 300 cambios conoce implícitamente el modelo de amenazas.
Ningún agente se filtra al contexto de otro. Un dominio claro = memoria útil que se acumula en el lugar correcto.
Abrir una tarea en N ramas, ejecutarlas al mismo tiempo y unir los resultados. Es algo que un loop no hace.
La unión es donde reside el peligro: una fusión mal hecha se traga una fuente en silencio, sin ninguna alerta.
Fan-out/fan-in es la primitiva de grafo que la Ruta 2 ya señalaba como el límite honesto del loop.
La arista elige el destino a partir del resultado del nodo: la complejidad baja va a la respuesta preparada, la media al agente de IA, y la alta o riesgosa se escala directamente a una persona.
También existe la arista de "no lo resolvió", que devuelve al siguiente camino, y la de aprendizaje, que vuelve al clasificador.
El enrutamiento por condición es lo que evita gastar un agente costoso en algo simple y a una persona en algo trivial.
La regla a la que convergió la industria: el código controla el enrutamiento predecible; el modelo se encarga de los pasos que requieren interpretación o criterio.
Enrutar con un modelo algo que resuelve un `if` es costoso, lento y no determinista: un puro desperdicio.
División del trabajo: código = predecible, modelo = criterio. Esa línea organiza todo el grafo de trabajo.
🔭 Fallas, harness y observabilidad
Lo que obtienes junto con el grafo. Modos de falla que el bucle no tenía, el harness que se convierte en runtime y la observabilidad sin la cual depuras a ciegas.
En fan-in, una rama falla o vuelve vacía y la unión sigue como si estuviera completa. El resultado parece bueno y está incompleto.
Este tipo de error no activa ninguna alarma — el panel sigue limpio mientras falta una fuente completa.
La unión debe comprobar la cardinalidad: ¿recibí los N que despaché? Sin esa comprobación, la fusión miente.
Dos aristas condicionales que se apuntan entre sí: el revisor rechaza, el escritor reescribe, el revisor vuelve a rechazar, para siempre.
Y es un ciclo sin progreso: la misma falla estructural de un loop sin condición de parada, solo que oculta dentro de un grafo.
Todo ciclo necesita un límite de iteraciones y un criterio de progreso. Sin ambos, el grafo nunca termina.
Un nodo transmite más de lo debido y el contexto limpio del siguiente nodo deja de estar limpio.
El revisor que recibe el razonamiento del escritor vuelve a aprobar el trabajo: el mismo problema del módulo 2.2, solo que reintroducido por el grafo.
La filtración de estado anula la principal ventaja del grafo: el contexto separado por función.
Declara explícitamente qué lleva cada arista, con nombre y formato.
Sin él, cada cambio en un nodo rompe silenciosamente al vecino: el mismo tipo de fallo de integración que sufre cualquier API sin contrato.
State schema es el contrato entre los nodos. Es el documento que formaliza lo que el módulo 4.1 llamó "estado".
Un grafo que se ejecuta en producción debe sobrevivir a fallos a mitad de la ejecución: reanudar desde donde se detuvo, no repetir lo que ya terminó y ser reproducible.
Es lo mismo que la orquestación de datos resuelve desde hace décadas — y es aquí donde el grafo agéntico hereda un problema ya resuelto.
Durabilidad = punto de control por nodo + idempotencia. Sin eso, cada error hace que haya que ejecutar todo el grafo de nuevo.
El harness del grafo debe mostrar qué nodos se ejecutaron, en qué orden, con qué latencia y a qué costo.
En un loop, «¿por qué hizo eso?» está enterrado en una transcripción; en un grafo, puedes consultar el camino recorrido como un dato.
Sin esta instrumentación pierdes precisamente la ventaja que motivó el grafo: visibilidad estructurada.