Graphs

At its core, LangGraph4j models agent workflows as graphs. You define the behavior of your agents using three key components:

1. State: A shared data structure that represents the current snapshot of your application. It is represented by an AgentState object.

2. Nodes: A Functional Interface (AsyncNodeAction) that encode the logic of your agents. They receive the current State as input, perform some computation or side-effect, and return an updated State.

3. Edges: A Functional Interface (AsyncEdgeAction) that determine which Node to execute next based on the current State. They can be conditional branches or fixed transitions.

By composing Nodes and Edges, you can create complex, looping workflows that evolve the State over time. The real power, though, comes from how LangGraph4j manages that State. To emphasize: Nodes and Edges are like functions - they can contain an LLM or just Java code.

In short: nodes do the work. edges tell what to do next.

// compile your graph
var graph = graphBuilder.compile(...);

State

The first thing you do when you define a graph is define the State of the graph. The State consists of the schema of the graph as well as reducer functions which specify how to apply updates to the state. The schema of the State will be the input schema to all Nodes and Edges in the graph, and should be defined using a map of Channel object. All Nodes will emit updates to the State which are then applied using the specified reducer function.

static class MessagesState extends AgentState {

    static Map<String, Channel<?>> SCHEMA = mapOf(
            "messages", AppenderChannel.<String>of(ArrayList::new)
    );
}

var graphBuilder = new StateGraph<>( MessagesState.SCHEMA, MessagesState::new)

static class MyState extends AgentState {

    static Map<String, Channel<?>> SCHEMA = mapOf(
            "property", Channel.<String>of( ( oldValue, newValue ) -> newValue.toUpperCase() )
    );
}

var graphBuilder = new StateGraph<>( MessagesState.SCHEMA, MyState::new)

Nodes

In LangGraph4j, nodes are typically a Functional Interface (AsyncNodeAction) where the argument is the state, you add these nodes to a graph using the addNode method:

import static org.bsc.langgraph4j.action.AsyncEdgeAction.edge_async;
import static org.bsc.langgraph4j.action.AsyncNodeAction.node_async;
import static org.bsc.langgraph4j.utils.CollectionsUtils.mapOf;

public class State extends AgentState {

  public State(Map<String, Object> initData) {
    super( initData  );
  }

  Optional<String> input() { return value("input"); } 
  Optional<String> results() { return value("results"); } 
 
}

AsyncNodeAction<State> myNode = node_async(state -> {
    System.out.println( "In myNode: " );
    return mapOf( results: "Hello " + state.input().orElse( "" ) );  
});

AsyncNodeAction<State> myOtherNode = node_async(state -> state);

var builder = new StateGraph( State::new )
  .addNode("myNode", myNode)
  .addNode("myOtherNode", myOtherNode)

Since AsyncNodeAction is designed to work with CompletableFuture, you can use node_async static method that adapt it to a simpler syncronous scenario.

import static org.bsc.langgraph4j.StateGraph.START;

graph.addEdge(START, "nodeA");

import static org.bsc.langgraph4j.StateGraph.END;

graph.addEdge("nodeA", END);

Edges

Edges define how the logic is routed and how the graph decides to stop. This is a big part of how your agents work and how different nodes communicate with each other. There are a few key types of edges:

• Normal Edges:

  Go directly from one node to the next.

• Conditional Edges:

  Call a function to determine which node(s) to go to next.

• Entry Point:

  Which node to call first when user input arrives.

• Conditional Entry Point:

  Call a function to determine which node(s) to call first when user input arrives.

// add a normal edge
graph.addEdge("nodeA", "nodeB");

import static org.bsc.langgraph4j.utils.CollectionsUtils.mapOf;

graph.addConditionalEdges("nodeA", routingFunction, mapOf( "first": "nodeB", "second": "nodeC" ) );

import static org.bsc.langgraph4j.StateGraph.START;

graph.addEdge(START, "nodeA");

import static org.bsc.langgraph4j.StateGraph.START;
import static org.bsc.langgraph4j.utils.CollectionsUtils.mapOf;

graph.addConditionalEdges(START, routingFunction, mapOf( "first": "nodeB", "second": "nodeC" ) );

Checkpointer

LangGraph4j has a built-in persistence layer, implemented through Checkpointers. When you use a checkpointer with a graph, you can interact with the state of that graph. When you use a checkpointer with a graph, you can interact with and manage the graph's state. The checkpointer saves a checkpoint of the graph state at every step, enabling several powerful capabilities:

First, checkpointers facilitate human-in-the-loop workflows workflows by allowing humans to inspect, interrupt, and approve steps. Checkpointers are needed for these workflows as the human has to be able to view the state of a graph at any point in time, and the graph has to be to resume execution after the human has made any updates to the state.

Second, it allows for “memory” between interactions. You can use checkpointers to create threads and save the state of a thread after a graph executes. In the case of repeated human interactions (like conversations) any follow up messages can be sent to that checkpoint, which will retain its memory of previous ones.

See this guide for how to add a checkpointer to your graph.

Threads

Threads enable the checkpointing of multiple different runs, making them essential for multi-tenant chat applications and other scenarios where maintaining separate states is necessary. A thread is a unique ID assigned to a series of checkpoints saved by a checkpointer. When using a checkpointer, you must specify a thread_id when running the graph.

thread_id is simply the ID of a thread. This is always required

You must pass these when invoking the graph as part of the configurable part of the config.

RunnableConfig config = RunnableConfig.builder()
                                  .threadId("a")
                                  .build();
graph.invoke(inputs, config);

See this guide for how to use threads.

Checkpointer state

When interacting with the checkpointer state, you must specify a thread identifier. Each checkpoint saved by the checkpointer has two properties:

• state: This is the value of the state at this point in time.
• nextNodeId: This is the Idenfier of the node to execute next in the graph.

Breakpoints

It can often be useful to set breakpoints before or after certain nodes execute. This can be used to wait for human approval before continuing. These can be set when you “compile” a graph. You can set breakpoints either before a node executes (using interruptBefore) or after a node executes (using interruptAfter.)

You MUST use a checkpoiner when using breakpoints. This is because your graph needs to be able to resume execution.

In order to resume execution, you can just invoke your graph with null as the input.

// Initial run of graph
graph.invoke(inputs, config);

// Let's assume it hit a breakpoint somewhere, you can then resume by passing in None
graph.invoke(null, config);

See this guide for a full walkthrough of how to add breakpoints.

Visualization

It's often nice to be able to visualize graphs, especially as they get more complex. LangGraph4j comes with several built-in ways to visualize graphs using diagram-as-code tools such as PlantUML and Mermaid through the graph.getGraph method.

// for PlantUML
GraphRepresentation result = app.getGraph(GraphRepresentation.Type.PLANTUML);

System.out.println(result.getContent());

// for Mermaid
GraphRepresentation result = app.getGraph(GraphRepresentation.Type.MERMAID);
System.out.println(result.getContent());