Visión general de la arquitectura de LangGraph
En una frase
LangGraph es un framework de orquestación de agentes basado en máquinas de estados con un núcleo de Channel + bucle Pregel: en la capa de construcción, StateGraph compila nodos y bordes en un ejecutable Pregel; en tiempo de ejecución, PregelLoop.tick ejecuta repetidamente «leer channel → dispatcher tareas → escribir channel → checkpoint» hasta converger. Durante el proceso emite salida multi-modo vía StreamMux, implementa colaboración humano-máquina mediante interrupt/Command, delega la persistencia a nivel de hilo a la familia BaseCheckpointSaver, y ofrece una API funcional equivalente con @entrypoint/@task.
Capas
Una frase por capa
- Inicio y configuración:RunnableConfig transporta thread_id/store/checkpointer; StateSnapshot es la instantánea inmutable devuelta por get_state.
- Construcción de Graph:StateGraph es la entrada del usuario; add_node/add_edge/add_conditional_edges definen la topología; compile produce CompiledStateGraph (es decir, una instancia de Pregel).
- Motor Pregel:Pregel es el producto de la compilación; stream/invoke/astream son las entradas; PregelLoop.tick ejecuta un paso; PregelRunner corre tareas en paralelo; _algo se encarga de la preparación de tareas, la escritura y la decisión de interrupción.
- Channel:BaseChannel abstrae la semántica update/consume/checkpoint; LastValue es la sobrescritura por defecto; Topic es pub/sub; Binop es la agregación por operador binario.
- Checkpoint:BaseCheckpointSaver expone put/get/list; tres implementaciones InMemory/Sqlite/Postgres; soporta síncrono y asíncrono.
- Streaming:StreamMux hace mux/demux multi-modo; cada transformer (values/updates/messages/debug/lifecycle/subgraph/checkpoints/tasks) produce una vista distinta.
- API funcional:@entrypoint convierte una función en un ejecutable Pregel; @task declara subtareas que pueden correr en paralelo.
- Interrupción y subgrafo:interrupt() dispara una interrupción humano-máquina; Command(resume/goto/update) dirige la resumición y los saltos; Send implementa fan-out.
Motivación del diseño por capas
LangGraph desacopla por completo «cómo se define el grafo» (graph), «cómo se ejecuta» (Pregel), «cómo se actualiza el estado» (channel), «cómo se persiste» (checkpoint), «cómo se observa» (stream), «cómo se expresa funcionalmente» (func), «cómo se dialoga con el humano» (interrupt) y «cómo se orquesta» (subgraph). Así, cambiar el backend de checkpoint no afecta la lógica de ejecución; cambiar el modo de stream no afecta la definición del grafo; añadir interrupciones no altera el channel. Pregel es el único centro: todas las rutas de ejecución terminan atravesando PregelLoop.tick.
Lecturas erróneas comunes
- «LangGraph es solo un envoltorio de grafo de LangChain»: no. Tiene un motor de ejecución Pregel independiente, no depende de las abstracciones chain/agent de LangChain y puede usarse por separado.
- «channel es state»: channel es la capa semántica de actualización del estado; los distintos tipos de channel (LastValue/Topic/Binop) deciden cómo se fusiona el estado, ahí radica lo que lo supera a una máquina de estados corriente.
- «@entrypoint es azúcar sintáctico de StateGraph»: funcionalmente equivalente pero de implementación distinta; la API func pasa por la ruta FunctionalAPI y al final también se compila a Pregel, pero su semántica de concurrencia y join se acerca más a la de una función normal.
Orden de lectura recomendado
Empieza por Inicio y configuración, luego StateGraph y el motor Pregel; después sigue el orden PregelLoop tick → Channel → Checkpoint → Streaming → API funcional → Interrupción y resumen → Orquestación de subgrafos.
Véase la documentación oficial: LangGraph docs · GitHub