LangGraph

1. Visión general del concepto y problema sistémico

Los intentos de construir un agente de producción confiable utilizando simples ciclos while True en Python o cadenas lineales se enfrentan rápidamente a limitaciones críticas de ingeniería:

1. Falta de persistencia: Si el servidor se reinicia durante un proceso de agente de 5 minutos, todo el estado actual y el progreso se pierden irremediablemente.
2. Incontrolabilidad del flujo (Black Box Problem): Es difícil predecir en qué momento el agente decidirá finalizar su trabajo, o cómo forzarlo a retroceder un paso en caso de un error de validación.
3. Imposibilidad de pausas prolongadas (Human-in-the-Loop): Detener la ejecución del programa esperando la confirmación del usuario sin bloquear la memoria del proceso en código convencional es extremadamente complicado.

LangGraph resuelve estos problemas modelando sistemas de agentes como Gráficos de Estado (Stateful Graphs). Cualquier proceso complejo se descompone en nodos transparentes (Nodes), bordes de transición (Edges) y un único estado tipificado (State), que se fija de manera atómica en la base de datos después de cada paso.

2. Taxonomía arquitectónica y modelo mental

La arquitectura de LangGraph se basa en cuatro entidades clave:

• 1. Shared State (Estado Compartido): Interfaz estrictamente tipificada (a través de TypedDict o Pydantic). Define el esquema de datos accesibles a todos los nodos. Para los campos, se pueden establecer reductores específicos (Reducers), como Annotated[list, add_messages], que automáticamente añaden nuevos mensajes en lugar de sobrescribir el array.
• 2. Nodes (Nodos del gráfico): Funciones síncronas o asíncronas comunes. Cada nodo recibe el estado actual, realiza cálculos (llamada a un modelo, ejecución de pruebas o acceso a la base de datos) y devuelve una actualización parcial del estado (State Delta).
• 3. Edges & Conditional Edges (Bordes de transición):
  • Bordes normales: transición determinista de nodo A a nodo B.
  • Bordes condicionales: una función enrutadora analiza la última salida del modelo y decide hacia dónde dirigir el flujo (por ejemplo: si se ha llamado a una herramienta — ir a tools, si se ha encontrado una respuesta final — ir a END).
• 4. Checkpointers (Checkpointers): Controladores de almacenamiento a largo plazo (MemorySaver para pruebas, PostgresSaver / SqliteSaver para producción). Crean instantáneas inmutables (Snapshots) en cada superpaso.

3. Pipeline técnico y mecánica interna

La ejecución del gráfico se realiza bajo el modelo de paralelismo sincrónico masivo (Bulk Synchronous Parallel, BSP):

1. State Initialization (Inicialización del estado): El gráfico recibe la entrada inicial y un objeto de configuración con la clave thread_id. El Checkpointer carga el último estado guardado para este hilo.
2. Superstep Execution (Ejecución del superpaso): Todos los nodos activos de la fase actual se ejecutan en paralelo. Cada nodo lee la misma instantánea del estado y genera su propio parche de actualización.
3. Reducer Aggregation & Checkpoint Commit (Agregación de estado y confirmación de checkpoint): Tras la finalización del trabajo de todos los nodos de la fase, el sistema aplica los reductores a los cambios obtenidos, forma un nuevo estado y lo fija atómicamente en la base de datos.
4. Edge Routing & Interrupt Inspection (Enrutamiento de bordes y verificación de interrupciones): Se evalúan las transiciones condicionales. Si el gráfico alcanza un punto de interrupción (interrupt_before), la ejecución se completa de manera segura, cediendo el control a la aplicación externa.

4. Escenarios prácticos de ingeniería en producción

01. Ciclo autónomo de desarrollo y corrección de errores de código

Gráfico de cuatro nodos:

• generate_code -> run_unit_tests -> evaluate_output.
• Si las pruebas son exitosas — transición a create_pr.
• Si las pruebas fallan — un borde condicional regresa al estado en generate_code junto con el stack trace del error (con un límite de máximo 5 iteraciones).

02. Proceso financiero Human-in-the-Loop

El agente analiza cuentas conflictivas de clientes. Si el monto del reembolso es menor a $100, el gráfico ejecuta el reembolso automáticamente a través del nodo execute_refund. Si el monto es mayor — el gráfico se interrumpe (interrupt), genera un enlace al formulario de aprobación para el gerente y reanuda el trabajo solo después de recibir un webhook de la persona.

03. Sistema multiagente "Supervisor — Especialistas"

El nodo central Supervisor actúa como enrutador de nivel superior. Dependiendo del tipo de tarea, cambia el contexto entre subgráficos especializados: ResearchSubgraph (búsqueda en internet y análisis) y DraftingSubgraph (generación de contratos), controlando un único contexto corporativo.

5. Errores comunes, trampas y seguridad

• State Bloat (Inflación del estado): Almacenar archivos PDF de gigabytes o tablas masivas en el estado compartido provoca que cada checkpoint en PostgreSQL tarde cientos de milisegundos. Almacena solo metadatos ligeros y URLs de artefactos en S3 en el estado.
• Recursion Limit Exceeded (Límite de recursión excedido): Si los bordes condicionales no tienen una salida garantizada del ciclo, la ejecución fallará con un error del sistema al alcanzar el límite de profundidad (por defecto 25 pasos). Siempre controla el contador de intentos directamente en el esquema de estado.
• Non-serializable Objects in State (Objetos no serializables en el estado): Intentar guardar en el estado un descriptor de archivo abierto, una conexión a la base de datos o un cierre funcional resultará en la caída del Checkpointer al intentar serializar en JSON/Pickle.