0
# LangGraph4j Core
1

2
LangGraph4j is a Java library for building stateful, multi-agent applications with Large Language Models (LLMs). It provides a framework for creating cyclical graphs where different components (agents, tools, or custom logic) can interact in a stateful manner, enabling complex AI applications with memory, context awareness, and sophisticated control flow patterns.
3

4
## Package Information
5

6
- **Package Name**: langgraph4j-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.bsc.langgraph4j
10
- **Artifact ID**: langgraph4j-core
11
- **Installation**: Add to Maven dependencies:
12

13
```xml
14
<dependency>
15
    <groupId>org.bsc.langgraph4j</groupId>
16
    <artifactId>langgraph4j-core</artifactId>
17
    <version>1.6.4</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import org.bsc.langgraph4j.*;
25
import org.bsc.langgraph4j.action.*;
26
import org.bsc.langgraph4j.state.*;
27
import org.bsc.langgraph4j.checkpoint.*;
28
```
29

30
## Basic Usage
31

32
```java
33
import org.bsc.langgraph4j.*;
34
import org.bsc.langgraph4j.action.AsyncNodeAction;
35
import org.bsc.langgraph4j.state.AgentState;
36
import java.util.Map;
37
import java.util.concurrent.CompletableFuture;
38

39
// Define a custom state class
40
class MyState extends AgentState {
41
    public MyState(Map<String, Object> initData) {
42
        super(initData);
43
    }
44
}
45

46
// Create a state graph
47
StateGraph<MyState> workflow = new StateGraph<>(MyState::new);
48

49
// Add nodes with actions
50
workflow.addNode("start_node", (state) ->
51
    CompletableFuture.completedFuture(Map.of("processed", true))
52
);
53

54
workflow.addNode("end_node", (state) ->
55
    CompletableFuture.completedFuture(Map.of("finished", true))
56
);
57

58
// Add edges between nodes
59
workflow.addEdge("start_node", "end_node");
60
workflow.addEdge("end_node", StateGraph.END);
61

62
// Set entry point
63
workflow.addEdge(StateGraph.START, "start_node");
64

65
// Compile and run
66
CompiledGraph<MyState> app = workflow.compile();
67
Optional<MyState> result = app.invoke(Map.of("input", "Hello World"));
68
```
69

70
## Architecture
71

72
LangGraph4j is built around several key components:
73

74
- **State Management**: `AgentState` and `Channel` system for managing application state with configurable update patterns
75
- **Graph Structure**: `StateGraph` for defining workflows and `CompiledGraph` for execution
76
- **Action System**: Synchronous and asynchronous action interfaces for node logic
77
- **Checkpoint System**: Persistent state snapshots for debugging, resuming, and time travel
78
- **Configuration**: Fine-grained control over execution with `CompileConfig` and `RunnableConfig`
79
- **Streaming**: Real-time execution monitoring with streaming output support
80

81
## Capabilities
82

83
### Graph Construction and Management
84

85
Core functionality for building and managing stateful workflow graphs. Supports nodes, edges, conditional routing, and subgraphs.
86

87
```java { .api }
88
class StateGraph<State extends AgentState> {
89
    StateGraph<State> addNode(String id, AsyncNodeAction<State> action);
90
    StateGraph<State> addNode(String id, AsyncNodeActionWithConfig<State> action);
91
    StateGraph<State> addEdge(String sourceId, String targetId);
92
    StateGraph<State> addConditionalEdges(String sourceId, AsyncCommandAction<State> condition, Map<String, String> mappings);
93
    CompiledGraph<State> compile();
94
    CompiledGraph<State> compile(CompileConfig config);
95
}
96
```
97

98
[Graph Construction](./graph-construction.md)
99

100
### Graph Execution and Control
101

102
Execute compiled graphs with sophisticated control flow, streaming, and state management. Support for synchronous execution, streaming outputs, and state snapshots.
103

104
```java { .api }
105
class CompiledGraph<State extends AgentState> {
106
    Optional<State> invoke(Map<String, Object> inputs);
107
    Optional<State> invoke(GraphInput input, RunnableConfig config);
108
    AsyncGenerator<NodeOutput<State>> stream(Map<String, Object> inputs, RunnableConfig config);
109
    AsyncGenerator<NodeOutput<State>> streamSnapshots(Map<String, Object> inputs, RunnableConfig config);
110
}
111
```
112

113
[Graph Execution](./graph-execution.md)
114

115
### State Management System
116

117
Comprehensive state management with channels, serialization, and update strategies. Handles complex state updates with merge functions and conflict resolution.
118

119
```java { .api }
120
class AgentState {
121
    Map<String, Object> data();
122
    <T> Optional<T> value(String key);
123
    static Map<String, Object> updateState(Map<String, Object> state, Map<String, Object> partialState, Map<String, Channel<?>> channels);
124
}
125

126
interface Channel<T> {
127
    Object update(String key, Object currentValue, Object newValue);
128
}
129
```
130

131
[State Management](./state-management.md)
132

133
### Action System and Node Logic
134

135
Define node behavior with synchronous and asynchronous actions. Support for configuration-aware actions and complex routing logic.
136

137
```java { .api }
138
@FunctionalInterface
139
interface AsyncNodeAction<S extends AgentState> {
140
    CompletableFuture<Map<String, Object>> apply(S state);
141
    static <S extends AgentState> AsyncNodeAction<S> node_async(NodeAction<S> syncAction);
142
}
143

144
@FunctionalInterface
145
interface AsyncCommandAction<S extends AgentState> {
146
    CompletableFuture<Command> apply(S state, RunnableConfig config);
147
}
148
```
149

150
[Actions and Node Logic](./actions.md)
151

152
### Checkpoint and Persistence
153

154
Persistent state management with checkpointing for debugging, resuming execution, and implementing human-in-the-loop workflows.
155

156
```java { .api }
157
interface BaseCheckpointSaver {
158
    Collection<Checkpoint> list(RunnableConfig config);
159
    Optional<Checkpoint> get(RunnableConfig config);
160
    RunnableConfig put(RunnableConfig config, Checkpoint checkpoint) throws Exception;
161
    Tag release(RunnableConfig config) throws Exception;
162
}
163

164
class Checkpoint {
165
    String getId();
166
    String getNodeId();
167
    String getNextNodeId();
168
    Map<String, Object> getState();
169
}
170
```
171

172
[Checkpoints and Persistence](./checkpoints.md)
173

174
### Configuration and Runtime Control
175

176
Configure graph compilation and execution behavior with interrupts, thread management, and metadata handling.
177

178
```java { .api }
179
class CompileConfig {
180
    Optional<BaseCheckpointSaver> checkpointSaver();
181
    Set<String> interruptsBefore();
182
    Set<String> interruptsAfter();
183
    boolean releaseThread();
184
    static Builder builder();
185
}
186

187
class RunnableConfig {
188
    Optional<String> threadId();
189
    Optional<String> checkPointId();
190
    Optional<String> nextNode();
191
    StreamMode streamMode();
192
    Optional<Object> metadata(String key);
193
}
194
```
195

196
[Configuration](./configuration.md)
197

198
### Prebuilt Components
199

200
Ready-to-use components for common patterns like message handling and specialized state management.
201

202
```java { .api }
203
class MessagesState<T> extends AgentState {
204
    List<T> messages();
205
    Optional<T> lastMessage();
206
    Optional<T> lastMinus(int n);
207
    static final Map<String, Channel<?>> SCHEMA;
208
}
209

210
class MessagesStateGraph<T> extends StateGraph<MessagesState<T>> {
211
    MessagesStateGraph();
212
    MessagesStateGraph(StateSerializer<MessagesState<T>> stateSerializer);
213
}
214
```
215

216
[Prebuilt Components](./prebuilt.md)
217

218
## Types
219

220
```java { .api }
221
// Core state type
222
abstract class AgentState {
223
    static final Object MARK_FOR_REMOVAL;
224
    static final Object MARK_FOR_RESET;
225
}
226

227
// Command for routing control
228
class Command {
229
    String gotoNode();
230
    Map<String, Object> update();
231
}
232

233
// Graph input types
234
interface GraphInput {}
235
class GraphArgs implements GraphInput {
236
    Map<String, Object> value();
237
}
238
class GraphResume implements GraphInput {}
239

240
// Execution output
241
interface NodeOutput<State extends AgentState> {
242
    String node();
243
    State state();
244
}
245

246
// Stream modes
247
enum StreamMode {
248
    VALUES, SNAPSHOTS
249
}
250

251
// Diagram generation
252
enum GraphRepresentation.Type {
253
    PLANTUML, MERMAID
254
}
255

256
// Exception types
257
class GraphStateException extends RuntimeException {}
258
class GraphRunnerException extends RuntimeException {}
259
```