0
# LangGraph
1
2
LangGraph is a low-level orchestration framework for building controllable AI agents using a message-passing graph computation model. It provides reliable, persistent workflows with first-class streaming support, human-in-the-loop capabilities, and multi-agent system architecture for production-scale applications.
3
4
## Package Information
5
6
- **Package Name**: @langchain/langgraph
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @langchain/langgraph`
10
11
## Core Imports
12
13
```typescript
14
import { StateGraph, Annotation, START, END } from "@langchain/langgraph";
15
import { MemorySaver } from "@langchain/langgraph-checkpoint";
16
```
17
18
For web environments:
19
20
```typescript
21
import { StateGraph, Annotation, START, END } from "@langchain/langgraph/web";
22
```
23
24
For CommonJS:
25
26
```javascript
27
const { StateGraph, Annotation, START, END } = require("@langchain/langgraph");
28
```
29
30
## Basic Usage
31
32
```typescript
33
import { StateGraph, Annotation, START, END } from "@langchain/langgraph";
34
import { MemorySaver } from "@langchain/langgraph-checkpoint";
35
36
// Define state structure
37
const GraphAnnotation = Annotation.Root({
38
messages: Annotation<string[]>({
39
reducer: (x: string[], y: string[]) => x.concat(y),
40
default: () => [],
41
}),
42
});
43
44
// Define nodes
45
async function nodeA(state: typeof GraphAnnotation.State) {
46
return { messages: [`Node A processed: ${state.messages.length} messages`] };
47
}
48
49
async function nodeB(state: typeof GraphAnnotation.State) {
50
return { messages: [`Node B processed: ${state.messages.length} messages`] };
51
}
52
53
// Build and compile graph
54
const graph = new StateGraph(GraphAnnotation)
55
.addNode("nodeA", nodeA)
56
.addNode("nodeB", nodeB)
57
.addEdge(START, "nodeA")
58
.addEdge("nodeA", "nodeB")
59
.addEdge("nodeB", END)
60
.compile({
61
checkpointer: new MemorySaver(), // Enable persistence
62
});
63
64
// Execute graph
65
const result = await graph.invoke(
66
{ messages: ["Hello"] },
67
{ configurable: { thread_id: "1" } }
68
);
69
console.log(result.messages);
70
```
71
72
## Architecture
73
74
LangGraph is built on several key architectural layers:
75
76
- **Channels**: Low-level communication primitives for passing data between nodes
77
- **Checkpointers**: Persistence layer for state snapshots and time-travel debugging
78
- **Pregel**: Core execution engine based on Google's Pregel graph processing model
79
- **Graph APIs**: High-level interfaces (StateGraph, MessageGraph) for building workflows
80
- **Prebuilt Components**: Ready-to-use agents and tools for common patterns
81
82
## Capabilities
83
84
### Graph Construction
85
86
Core graph building functionality for creating stateful workflows with typed state management and node orchestration.
87
88
```typescript { .api }
89
class StateGraph<SD extends StateDefinition> {
90
constructor(stateSchema: SD);
91
addNode(key: string, action: NodeType<SD>): StateGraph<SD>;
92
addEdge(start: string, end: string): StateGraph<SD>;
93
addConditionalEdges(
94
source: string,
95
path: (state: StateType<SD>) => string | string[],
96
pathMap?: Record<string, string>
97
): StateGraph<SD>;
98
compile(options?: PregelOptions): CompiledStateGraph;
99
}
100
101
class Annotation {
102
static Root<T extends StateDefinition>(fields: T): AnnotationRoot<T>;
103
}
104
```
105
106
[Graph Construction](./graph-construction.md)
107
108
### State Management & Channels
109
110
Channel system for managing state communication and synchronization between graph nodes with various storage patterns.
111
112
```typescript { .api }
113
class BaseChannel {
114
update(values: any[]): any;
115
get(): any;
116
checkpoint(): any;
117
}
118
119
type LastValue<T> = T; // Channel storing most recent value
120
type Topic<T> = T[]; // Channel storing message history
121
type DynamicBarrierValue = any; // Dynamic synchronization barrier
122
```
123
124
[State Management & Channels](./state-channels.md)
125
126
### Execution & Runtime
127
128
Core execution engine providing streaming execution, runtime configuration, and graph processing capabilities.
129
130
```typescript { .api }
131
class Pregel<Nodes, Channels, ContextType, InputType, OutputType> {
132
invoke(
133
input: InputType,
134
config?: LangGraphRunnableConfig
135
): Promise<OutputType>;
136
stream(
137
input: InputType,
138
config?: LangGraphRunnableConfig
139
): AsyncIterableIterator<OutputType>;
140
streamMode: "values" | "updates" | "messages" | "checkpoints" | "debug";
141
}
142
```
143
144
[Execution & Runtime](./execution-runtime.md)
145
146
### Persistence & Checkpoints
147
148
State persistence system enabling checkpoint-based recovery, state history, and time-travel debugging for long-running workflows.
149
150
```typescript { .api }
151
class BaseCheckpointSaver {
152
put(
153
config: RunnableConfig,
154
checkpoint: Checkpoint,
155
metadata: CheckpointMetadata,
156
newVersions: ChannelVersions
157
): Promise<RunnableConfig>;
158
getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
159
list(
160
config: RunnableConfig,
161
options?: CheckpointListOptions
162
): AsyncGenerator<CheckpointTuple>;
163
}
164
165
class MemorySaver extends BaseCheckpointSaver {
166
constructor();
167
}
168
```
169
170
[Persistence & Checkpoints](./persistence-checkpoints.md)
171
172
### Prebuilt Agents & Components
173
174
Ready-to-use agent implementations and tool integration for common AI agent patterns like ReAct, function calling, and tool execution.
175
176
```typescript { .api }
177
function createReactAgent(params: CreateReactAgentParams): CompiledStateGraph;
178
function createAgentExecutor(config: AgentExecutorConfig): CompiledStateGraph;
179
180
class ToolNode {
181
constructor(tools: ToolType[], options?: ToolNodeOptions);
182
}
183
```
184
185
[Prebuilt Agents & Components](./prebuilt-agents.md)
186
187
### Human-in-the-Loop & Control Flow
188
189
Interactive workflow capabilities with interruption points, approval flows, and dynamic control flow for human oversight.
190
191
```typescript { .api }
192
function interrupt<I, R>(value: I): R;
193
function isInterrupted<Value>(values: unknown): values is Interrupt<Value>;
194
195
class Command<Resume, Update, Nodes> {
196
resume: Resume;
197
update: Update;
198
goto: Nodes;
199
}
200
201
class Send<Node, Args> {
202
node: Node;
203
args: Args;
204
}
205
```
206
207
[Human-in-the-Loop & Control Flow](./human-loop-control.md)
208
209
### Functional API & Tasks
210
211
Task-based programming interface providing functional composition patterns and declarative workflow definition.
212
213
```typescript { .api }
214
function task<ArgsT, OutputT>(
215
optionsOrName: TaskOptions | string,
216
func: TaskFunc<ArgsT, OutputT>
217
): (...args: ArgsT) => Promise<OutputT>;
218
219
function entrypoint<InputT, OutputT>(
220
optionsOrName: EntrypointOptions | string,
221
func: EntrypointFunc<InputT, OutputT>
222
): Pregel<...>;
223
```
224
225
[Functional API & Tasks](./functional-api.md)
226
227
### Remote Execution & Advanced Features
228
229
Distributed graph execution, schema integration, and advanced streaming capabilities for complex multi-system workflows.
230
231
```typescript { .api }
232
class RemoteGraph {
233
constructor(params: RemoteGraphParams);
234
invoke(input: any, config?: LangGraphRunnableConfig): Promise<any>;
235
}
236
237
function getStateTypeSchema(graph: unknown): JSONSchema | undefined;
238
function getUpdateTypeSchema(graph: unknown): JSONSchema | undefined;
239
```
240
241
[Remote Execution & Advanced Features](./remote-advanced.md)
242
243
## Error Handling
244
245
```typescript { .api }
246
class BaseLangGraphError extends Error {
247
name: string;
248
message: string;
249
}
250
251
class GraphInterrupt extends BaseLangGraphError {
252
constructor(value?: any);
253
}
254
255
class GraphRecursionError extends BaseLangGraphError {}
256
class GraphValueError extends BaseLangGraphError {}
257
class NodeInterrupt extends GraphInterrupt {}
258
```
259
260
## Common Constants
261
262
```typescript { .api }
263
const START: "__start__"; // Graph entry point
264
const END: "__end__"; // Graph termination
265
const INTERRUPT: "__interrupt__"; // Interruption marker
266
```