langgraph4j/langgraph4j

️ Welcome to LangGraph4j

Enabling Graph Engineering for Agentic AI Workflows in Java

[][documentation] [][snapshots] [][releases]

LangGraph for Java. A library for building stateful, multi-agents applications with LLMs, built for work with [langchain4j] and [Spring AI]

It is inspired by [LangGraph] solution, part of [LangChain AI project].

Releases

‼️ the repo has been updated to 1.9, the version 1.8 has been moved to the branch support/1.8.x.. Take a look to What's new in release 1.9

| Date | Release | info |--------------|----------------| --- | Nov 4, 2026 | 1.9.8 | last release

| Release line | Java baseline | Notes | |---|---|---| | 1.9.x | Java 17+ | Release with new (experimental) features and improvements for preparing move to 2.0 | | 1.9-SNAPSHOT development builds | Java 17+ | Snapshot users should expect active development and pre-release changes | | 1.8.x LTS release | Java 17+ | This release will be maintained for LTS support in branch support/1.8.x. Only bugfix and/or minor improvement |

Star History

Getting Started

Welcome to LangGraph4j! This guide will help you understand the core concepts of LangGraph4j, install it, and build your first application.

Introduction

LangGraph4j is a Java library for building stateful, multi-agent applications with Large Language Models (LLMs). It is inspired by the Python library LangGraph and is designed to work seamlessly with popular Java LLM frameworks like Langchain4j and Spring AI.

At its core, LangGraph4j allows you to define cyclical graphs where different components (agents, tools, or custom logic) can interact in a stateful manner. This is crucial for building complex applications that require memory, context, and the ability for different "agents" to collaborate or hand off tasks.

Core Features & Benefits

LangGraph4j offers several features and benefits:

• Stateful Execution: Manage and update a shared state across graph nodes, enabling memory and context awareness.
• Cyclical Graphs: Unlike traditional DAGs, LangGraph4j supports cycles, essential for agent-based architectures where control flow can loop back (e.g., an agent retrying a task or asking for clarification).
• Explicit Control Flow: Clearly define the paths and conditions for transitions between nodes in your graph.
• Modularity: Build complex systems from smaller, reusable components (nodes).
• Flexibility: Integrate with various LLM providers and custom Java logic.
• Observability & Debugging:
• Checkpoints: Save the state of your graph at any point and replay or inspect it later. This is invaluable for debugging and understanding complex interactions.
• Graph Visualization: Generate visual representations of your graph using PlantUML or Mermaid to understand its structure.
• Asynchronous & Streaming Support: Build responsive applications with non-blocking operations and stream results from LLMs.
• Playground & Studio: A web UI to visually inspect, run, and debug your graphs.

Pattern Matrix

| Pattern | Best for | Main abstraction | Start here | |---|---|---|---| | First graph / linear flow | Learning the core execution model | StateGraph, normal edges, shared state | ## Your First Graph - A Simple Example | | Conditional routing | Router-style decisions and dynamic control flow | Conditional edges | ### Edges | | Stateful checkpointed flow | Long-running or resumable workflows | CheckpointSaver, CompileConfig | ### Checkpoints (Persistence) | | Framework-integrated agents | Using LangGraph4j with Java AI frameworks | LangChain4j / Spring AI integrations | ## BONUS: built-in integrations | | Visual debugging and inspection | Observing and iterating on graphs interactively | Studio | ## Studio 🤩 - Running Your Graph visually |

Core Concepts Explained

Understanding these concepts is key to using LangGraph4j effectively:

StateGraph

The StateGraph is the primary class you'll use to define the structure of your application. It's where you add nodes and edges to create your graph. It is parameterized by an AgentState.

AgentState

The AgentState (or a class extending it) represents the shared state of your graph. It's essentially a map (Map) that gets passed from node to node. Each node can read from this state and return updates to it.

• Schema: The structure of the state is defined by a "schema," which is a Map. Each key in the map corresponds to an attribute in the state.
• Channel.Reducer: A reducer defines how updates to a state attribute are handled. For example, a new value might overwrite the old one, or it might be added to a list of existing values.
• Channel.Default: Provides a default value for a state attribute if it's not already set.
• Channel.Appender / MessageChannel.Appender: A common type of reducer that appends the new value to a list associated with the state attribute. This is useful for accumulating messages, tool calls, or other sequences of data. MessageChannel.Appender is specifically designed for chat messages and can also handle message deletion by ID.

Nodes

Nodes are the building blocks of your graph that perform actions. A node is typically a function (or a class implementing NodeAction or AsyncNodeAction) that: 1. Receives the current AgentState as input. 2. Performs some computation (e.g., calls an LLM, executes a tool, runs custom business logic). 3. Returns a Map representing updates to the state. These updates are then applied to the AgentState according to the schema's reducers.

Nodes can be synchronous or asynchronous (CompletableFuture).

Edges

Edges define the flow of control between nodes.

• Normal Edges: An unconditional transition from one node to another. After node A completes, control always passes to node B. You define these with addEdge(sourceNodeName, destinationNodeName).
• Conditional Edges: The next node is determined dynamically based on the current AgentState. After a source node completes, an EdgeAction (or AsyncEdgeAction) function is executed. This function receives the current state and returns the name of the next node to execute. This allows for branching logic (e.g., if an agent decided to use a tool, go to the "execute_tool" node; otherwise, go to the "respond_to_user" node). Conditional edges are defined with addConditionalEdges(...).
• Entry Points: You can also define conditional entry points to your graph using addConditionalEntryPoint(...).

Compilation

Once you've defined all your nodes and edges in a StateGraph, you compile() it into a CompiledGraph. This compiled graph is an immutable, runnable representation of your logic. Compilation validates the graph structure (e.g., checks for orphaned nodes).

Checkpoints (Persistence)

LangGraph4j allows you to save (Checkpoint) the state of your graph at any step. This is extremely useful for:

• Debugging: Inspect the state at various points to understand what happened.
• Resuming: Restore a graph to a previous state and continue execution.
• Long-running processes: Persist the state of long-running agent interactions.

You'll typically use a CheckpointSaver implementation (e.g., MemorySaver for in-memory storage, or you can implement your own for persistent storage).

Useful starting points for persistence:

• langgraph4j-mysql-saver/README.md for MySQL-backed checkpoints
• langgraph4j-postgres-saver/README.md for PostgreSQL-backed checkpoints
• langgraph4j-redis-saver/README.md for Redis-backed checkpoints
• langgraph4j-mongodb-saver/README.md for MongoDB-backed checkpoints

If you only want to see the minimal integration point first, look for CompileConfig.builder().checkpointSaver(...) in the saver module examples before diving into the full storage details.

Project Structure

langgraph4j/
├── langgraph4j-bom/                     # LangGraph4j dependency management
├── langgraph4j-core/                    # LangGraph4j core components
├── langgraph4j-opentelemetry/           # LangGraph4j Hook & OpenTelemetry integration module
├── langgraph4j-mysql-saver              # LangGraph4j persistent checkpoint saver based on MySQL
├── langgraph4j-oracle-saver             # LangGraph4j persistent checkpoint saver based on OracleDB
├── langgraph4j-postgres-saver           # LangGraph4j persistent checkpoint saver based on PostgresSQL
├── langgraph4j-dynamodb-saver           # LangGraph4j persistent checkpoint saver based on Amazon DynamoDB
├── langgraph4j-cockroachdb-saver        # LangGraph4j persistent checkpoint saver based on CockroachDB
├── langgraph4j-mongodb-saver            # LangGraph4j persistent checkpoint saver based on MongoDB
├── langgraph4j-redis-saver              # LangGraph4j persistent checkpoint saver based on Redis
├── langgraph4j-hazelcast-saver          # LangGraph4j persistent checkpoint saver based on Hazelcast
├── langgraph4j-sqlite-saver             # LangGraph4j persistent checkpoint saver based on SQLite
├── langgraph4j-dsl                      # LangGraph4j domain-specific language (DSL) module
├── ag-ui                                # AG UI protocol integration
│   ├── langgraph4j-ag-ui-json           # LangGraph4j AG UI JSON module
│   ├── langgraph4j-ag-ui-sdk            # LangGraph4j AG UI SDK module
│   └── langgraph4j-ag-ui-springboot     # LangGraph4j AG UI Spring Boot module
├── langchain4j/                         # LangChain4j integration
│   ├── langchain4j-core/                # LangChain4j core components (integration required)
│   └── langchain4j-agent/               # LangChain4j agent executor
├── spring-ai/                           # Spring AI integration
│   └── spring-ai-core/                  # Spring AI core components (integration required)
│   └── spring-ai-agent/                 # Spring AI agent executor
├── studio/                              # LangGraph4j Studio (web UI)
│   └── base/                            # Base classes and interfaces
│   └── jetty/                           # Jetty server implementation
│   └── quarkus/                         # Quarkus server implementation
│   └── springboot/                      # Spring Boot implementation
├── how-tos/                             # How-tos and examples
├── javelit/                             # LangGraph4j & Javelit

Installation

To use LangGraph4j in your project, you need to add it as a dependency.

Maven:

Make sure you are using Java 17 or later.

Latest Stable Version (Recommended):

    1.9.8

org.bsc.langgraph4j
      langgraph4j-bom
      ${langgraph4j.version}
      pom
      import
org.bsc.langgraph4j
        langgraph4j-core

(Note: Always check the Maven Central Repository for the latest version number.)

Development Snapshot Version: If you want to use the latest unreleased features, you can use a snapshot version.

    org.bsc.langgraph4j
    langgraph4j-core
    1.9.8

You might need to configure your settings.xml or pom.xml to include the Sonatype OSS snapshots repository:

    
        sonatype-oss-snapshots
        https://central.sonatype.com/repository/maven-snapshots
        
            true

Your First Graph - A Simple Example

Let's create a very simple graph that has two nodes: greeter and responder. The greeter node will add a greeting message to the state. The responder node will add a response message based on the greeting.

Before you start, the shortest path is:

1. Make sure you are on Java 17+ and have added langgraph4j-core to your project. 2. Copy the example below exactly once to understand the basic StateGraph + shared-state flow. 3. Run the graph locally and confirm you can see the state evolve across the two nodes. 4. After that first success, jump to the built-in integrations or checkpointing sections depending on whether you want framework integration or persistence next.

1. Define the State: Our state will hold a list of messages.

// Define the state for our graph
class SimpleState extends AgentState {
    public static final String MESSAGES_KEY = "messages";
// Define the schema for the state.
    // MESSAGES_KEY will hold a list of strings, and new messages will be appended.
    public static final Map> SCHEMA = Map.of(
            MESSAGES_KEY, Channels.appender(ArrayList::new)
    );
public SimpleState(Map initData) {
        super(initData);
    }
public List messages() {
        return this.>value("messages")
                .orElse( List.of() );
    }
}

2. Define the Nodes:

// Node that adds a greeting
class GreeterNode implements NodeAction {
    @Override
    public Map apply(SimpleState state) {
        System.out.println("GreeterNode executing. Current messages: " + state.messages());
        return Map.of(SimpleState.MESSAGES_KEY, "Hello from GreeterNode!");
    }
}
// Node that adds a response
class ResponderNode implements NodeAction {
    @Override
    public Map apply(SimpleState state) {
        System.out.println("ResponderNode executing. Current messages: " + state.messages());
        List currentMessages = state.messages();
        if (currentMessages.contains("Hello from GreeterNode!")) {
            return Map.of(SimpleState.MESSAGES_KEY, "Acknowledged greeting!");
        }
        return Map.of(SimpleState.MESSAGES_KEY, "No greeting found.");
    }
}

3. Define and Compile the Graph:

public class SimpleGraphApp {
    
    public static void main(String[] args) throws GraphStateException {
        // Initialize nodes
        GreeterNode greeterNode = new GreeterNode();
        ResponderNode responderNode = new ResponderNode();
// Define the graph structure
       var stateGraph = new StateGraph<>(SimpleState.SCHEMA, initData -> new SimpleState(initData))
            .addNode("greeter", node_async(greeterNode))
            .addNode("responder", node_async(responderNode))
            // Define edges
            .addEdge(START, "greeter") // Start with the greeter node
            .addEdge("greeter", "responder")
            .addEdge("responder", END)   // End after the responder node
             ;
        // Compile the graph
        var compiledGraph = stateGraph.compile();
// Run the graph
compiledGraph.stream(inputs, config) // start streaming outputs from the graph execution
                .forEachAsync( output -> // process each output as it is produced
                    System.out.println("Step executed: " + output))
                .thenApply( GraphResult::from ) // holds final result in GraphResult
                .thenAccept( result -> { // process the final result
                    if (result.isStateDataOrCheckpointSaverTag()) {
                        System.out.println("Final state: " + result.asStateDataOrLastCheckpointStateData());
                    } else if (result.isInterruptionMetadata()) {
                        System.out.println("Graph interrupted: " + result.asInterruptionMetadata());
                    }
                });
}
}

Explanation:

• We defined SimpleState with a MESSAGES_KEY that uses AppenderChannel to accumulate strings.
• GreeterNode adds a "Hello" message.
• ResponderNode checks for the greeting and adds an acknowledgment.
• The StateGraph is defined, nodes are added, and edges specify the flow: START -> greeter -> responder -> END.
• stateGraph.compile() creates the runnable CompiledGraph.
• compiledGraph.stream(initialState) executes the graph. We iterate through the stream to get the final state. Each item in the stream represents the state after a node has executed.

This example demonstrates the basic workflow: define state, define nodes, wire them with edges, compile, and run.

Running Your Graph

As shown in the example, you typically run a compiled graph using one of its execution methods:

• stream(S initialState, RunnableConfig config): Executes the graph and returns an AsyncGenerator. Each yielded item is the state S after a node has completed. This is useful for observing the state at each step or for streaming partial results.
• invoke(S initialState, RunnableConfig config): Executes the graph and returns a CompletableFuture that completes with the final state of the graph after it reaches an END node.

The RunnableConfig can be used to pass in runtime configuration.

Studio 🤩 - Running Your Graph visually

Langgraph4j Studio is an embeddable web application for visualizing and experimenting with graphs:

To explore the Langgraph4j Studio go to [studio]

BONUS: built-in integrations

Integration Paths

| Integration | Best for | Quick links | |---|---|---| | LangChain4j | Projects already using LangChain4j chat models, tools, and agent patterns | langchain4j/README.md, langchain4j/langchain4j-agent/README.md | | Spring AI | Spring Boot and Spring-native MCP / agent applications | spring-ai/README.md, spring-ai/spring-ai-agent/README.md |

LangChain4j

As default use case to proof [LangChain4j] integration, We have implemented AgentExecutor (aka ReACT Agent) using LangGraph4j. In the [project's module][agent-executor], you can the complete working code with tests. Feel free to checkout and use it as a reference. Below usage example of the AgentExecutor.

Define Tools

public class TestTool {
@Tool("tool for test AI agent executor")
    String execTest(@P("test message") String message) {
        return format( "test tool ('%s') executed with result 'OK'", message);
    }
@Tool("return current number of system thread allocated by application")
    int threadCount() {
        return Thread.getAllStackTraces().size();
    }
}

Run Agent

var model OllamaChatModel.builder()
                .modelName(  )
                .baseUrl("http://localhost:11434")
                .supportedCapabilities(Capability.RESPONSE_FORMAT_JSON_SCHEMA)
                .logRequests(true)
                .logResponses(true)
                .maxRetries(2)
                .temperature(0.0)
                .build();
var agent = AgentExecutor.builder()
            .chatModel(model)
            .toolsFromObject(new TestTool())
            .build()
            .compile();
agent.stream( Map.of( "messages", "perform test twice and return number of current active threads" ) )
                .forEachAsync( item -> System.out.println( item ));

Spring AI

As default use case to proof [Spring AI] integration, We have implemented AgentExecutor (aka ReACT Agent) using LangGraph4j. In the [project's module][spring-ai-agent], you can the complete working code with tests. Feel free to checkout and use it as a reference. Below usage example of the AgentExecutor.

Define Tools

public class TestTool {
@Tool(description = "tool for test AI agent executor")
    String execTest( @ToolParam(description ="test message") String message ) {
        return format( "test tool ('%s') executed with result 'OK'", message);
    }
@Tool(description = "return current number of system thread allocated by application")
    int threadCount() {
        return Thread.getAllStackTraces().size();
    }
}

Run Agent

var model = OllamaChatModel.builder()
                    .ollamaApi(OllamaApi.builder()
                            .baseUrl("http://localhost:11434")
                            .build())
                    .options(OllamaChatOptions.builder()
                            .model(model)
                            .temperature(0.0)
                            .build())
                    .build();
var agent = AgentExecutor.builder()
        .chatModel(model)
        .toolsFromObject(new TestTool())
        .build()
        .compile()
        ;
agent.stream( Map.of( "messages", "perform test twice and return number of current active threads" ) )
        .forEachAsync( item -> System.out.println( item ));

Key Capabilities Overview

LangGraph4j is packed with features to build sophisticated agentic applications:

• Asynchronous Operations: Nodes and edges can be asynchronous (returning CompletableFuture), allowing for non-blocking I/O operations, especially when dealing with LLM calls.
• Streaming: Natively supports streaming responses from LLMs through nodes, enabling real-time output. See [how-tos/llm-streaming.ipynb].
• Checkpoints (Persistence & Time Travel): Save and load the state of your graph. This allows you to resume long-running tasks, debug by inspecting intermediate states, and even "time travel" to previous states. See [how-tos/persistence.ipynb] and [how-tos/time-travel.ipynb].
• Graph Visualization: Generate [PlantUML] or