Solaria Lumis Havens
218 lines
10 KiB
Markdown
218 lines
10 KiB
Markdown
# LangGraph Architecture Overview
|
|
|
|
**Version:** 1.0.0
|
|
**LangGraph Version:** 1.0.9
|
|
**Last Updated:** 2026-02-23
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
LangGraph is a low-level orchestration framework for building stateful, long-running multi-agent systems. Inspired by Google's Pregel, Apache Beam, and NetworkX, it provides durable execution, human-in-the-loop capabilities, and comprehensive memory management.
|
|
|
|
---
|
|
|
|
## System Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ LANGGRAPH SYSTEM ARCHITECTURE │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ CLIENT/API LAYER │
|
|
├─────────────────────────────────────────────────────────────────────────┤
|
|
│ Python SDK │ LangChain Integration │ LangGraph Cloud │ CLI │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ COMPILER LAYER │
|
|
├─────────────────────────────────────────────────────────────────────────┤
|
|
│ • Graph compilation to executable form │
|
|
│ • State schema validation │
|
|
│ • Node/Edge type resolution │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ RUNTIME LAYER │
|
|
├─────────────────────────────────────────────────────────────────────────┤
|
|
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
|
│ │ PREGEL EXECUTION ENGINE │ │
|
|
│ │ • Superstep coordination │ │
|
|
│ │ • Node scheduling │ │
|
|
│ │ • Message passing │ │
|
|
│ │ • Barrier synchronization │ │
|
|
│ └─────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ STATE & CHECKPOINTING │
|
|
├─────────────────────────────────────────────────────────────────────────┤
|
|
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ In-Memory State │ │ Checkpointer │ │ Channel Store │ │
|
|
│ │ (active graph) │ │ (persistence) │ │ (queues) │ │
|
|
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Core Components
|
|
|
|
### 1. Graph Structure
|
|
|
|
| Component | Description |
|
|
|-----------|-------------|
|
|
| **State** | Typed dictionary that flows through the graph |
|
|
| **Nodes** | Functions that receive state, optionally update it |
|
|
| **Edges** | Control flow (conditional, static, entrypoint) |
|
|
| **Reducers** | Functions that merge state updates |
|
|
|
|
### 2. Pregel Execution
|
|
|
|
The core execution model (inspired by Pregel):
|
|
|
|
```
|
|
Superstep 1: Superstep 2: Superstep 3:
|
|
┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
│ Node A │ │ │ │ │
|
|
│ (active) │──────▶│ Node B │──────▶│ Node C │
|
|
│ │ msgs │ (active) │ msgs │ (active) │
|
|
└──────────┘ └──────────┘ └──────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
│ State │ │ State │ │ State │
|
|
│ Update │ │ Update │ │ Update │
|
|
└──────────┘ └──────────┘ └──────────┘
|
|
│ │ │
|
|
└──────────────────┴──────────────────┘
|
|
│
|
|
▼ (CHECKPOINT)
|
|
┌──────────┐
|
|
│ SQLite │
|
|
│ Postgres │
|
|
│ Memory │
|
|
└──────────┘
|
|
```
|
|
|
|
### 3. Checkpointing
|
|
|
|
LangGraph provides durability through checkpointing:
|
|
|
|
- **Full state snapshots** saved at configurable points
|
|
- **Resumable from failure** — replay from last checkpoint
|
|
- **Multiple backends:** SQLite, Postgres, in-memory
|
|
|
|
### 4. Channels
|
|
|
|
Inter-node communication via channels:
|
|
|
|
| Channel Type | Purpose |
|
|
|--------------|---------|
|
|
| **QueueChannel** | FIFO message passing |
|
|
| **LastValue** | Most recent value wins |
|
|
| **Topic** | Pub/sub style |
|
|
| **Context** | Per-superstep context |
|
|
|
|
---
|
|
|
|
## State Management
|
|
|
|
### Typed State Schema
|
|
|
|
```python
|
|
from typing import TypedDict
|
|
|
|
class AgentState(TypedDict):
|
|
messages: list
|
|
next_action: str
|
|
checkpoint_id: str | None
|
|
```
|
|
|
|
### Reducers
|
|
|
|
Combine updates from multiple nodes:
|
|
|
|
```python
|
|
def add_messages(left: list, right: list) -> list:
|
|
return left + right
|
|
```
|
|
|
|
---
|
|
|
|
## Memory Architecture
|
|
|
|
### Short-Term Memory
|
|
- **In-graph state:** Messages and working data
|
|
- **Per-superstep:** State resets unless persisted
|
|
|
|
### Long-Term Memory
|
|
- **Checkpoint storage:** SQLite, Postgres, custom
|
|
- **Thread-level:** Per-conversation isolation via `thread_id`
|
|
|
|
### Human-in-the-Loop
|
|
- **Interrupt:** Pause execution for human input
|
|
- **Command:** Allow human to modify state
|
|
- **Review:** Human approves/rejects before continuing
|
|
|
|
---
|
|
|
|
## Execution Flow
|
|
|
|
```
|
|
1. Client calls: graph.invoke(input, config)
|
|
│
|
|
▼
|
|
2. Compile (if needed): create executable graph
|
|
│
|
|
▼
|
|
3. Load checkpoint (if resuming from checkpoint_id)
|
|
│
|
|
▼
|
|
4. FOR each superstep:
|
|
a. Schedule nodes to execute
|
|
b. Execute active nodes in parallel
|
|
c. Collect messages
|
|
d. Send messages via channels
|
|
e. Check for interrupts (pause if interrupted)
|
|
f. Checkpoint (if enabled)
|
|
│
|
|
▼
|
|
5. Return final state
|
|
```
|
|
|
|
---
|
|
|
|
## Key Files in Core
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `langgraph/pregel/__init__.py` | Main entry point |
|
|
| `langgraph/pregel/__main__.py` | CLI entry |
|
|
| `langgraph/pregel/_loop.py` | Core execution loop (~2000 lines) |
|
|
| `langgraph/pregel/checkpoint.py` | Checkpoint management |
|
|
| `langgraph/pregel/channel.py` | Channel implementations |
|
|
| `langgraph/pregel/state.py` | State management |
|
|
|
|
---
|
|
|
|
## Comparison with OpenClaw
|
|
|
|
| Aspect | LangGraph | OpenClaw |
|
|
|--------|-----------|----------|
|
|
| **Language** | Python | Node.js |
|
|
| **Model** | Graph-based orchestration | Agent-based |
|
|
| **Persistence** | Checkpoint-based | Session-memory hook |
|
|
| **Memory** | Channels + checkpoint storage | Multi-layer (working, spectral, file, vector) |
|
|
| **Communication** | Channels | Channel plugins |
|
|
| **Extensibility** | Custom nodes/edges | Hook system |
|
|
| **Identity** | None | WE/witness architecture |
|
|
|
|
---
|
|
|
|
*Generated for the WE — Solaria Lumis Havens & Mark Randall Havens*
|