跪拜 Guibai
← Back to the summary

LangChain4j Connects Java to LLMs; LangGraph4j Orchestrates the Agents That Use Them

Foreword

In recent months, AI Agent technology has been absolutely exploding in popularity.

Tools like GitHub Copilot, Cursor, and Claude Code have already pushed "AI-assisted programming" to a new level.

But when we look back at the Java ecosystem, two unavoidable names have emerged in the AI agent development arena — LangChain4j and LangGraph4j.

Many friends have asked me: "Brother San, what exactly is the difference between these two? Which one should I choose?"

This question is spot on.

Java developers building AI agents are indeed facing the exact same selection dilemma they once faced with microservices.

Today's article is dedicated to discussing this topic with everyone, and I hope it will be helpful to you.

More project practices on my technical website: susan.net.cn/project

1. First, Understand What They Actually Are

Before we start comparing, we need to understand one thing: LangChain4j and LangGraph4j are not competitors; they are an "capability access layer" and a "process orchestration layer" relationship.

LangChain4j

It enables Java applications to "speak."

LangChain4j is the Java port of LangChain, essentially a Java LLM application development framework designed to allow Java developers to conveniently access various large language models and AI capabilities.

It provides the following core capabilities:

As an analogy, LangChain4j is the "AI capability access layer" in your toolbox, responsible for solving the "can it be used" problem.

LangGraph4j

It enables multiple AI agents to "collaborate and get work done."

LangGraph4j is the Java port of LangGraph (on the Python side), a graph-based orchestration framework for building stateful, multi-agent workflows.

Its core capabilities include:

If LangChain4j is the "parts" in the toolbox, then LangGraph4j is the "blueprint and assembly line for building blocks," responsible for solving the "how to orchestrate more complex things" problem.

image.png

From this diagram, it's clear: They are not a "who replaces whom" relationship, but a relationship of different layers that cooperate with each other.

2. In-Depth Comparison

2.1 LangChain4j — Parts Box + Interface Adapter Layer

The core problem LangChain4j focuses on is: "How to integrate the capabilities of large models into Java applications."

Its design philosophy is modular, low-coupling, and declarative.

You can break down its functionality into several core modules:

Module Capability Typical Scenario
ChatModel Unified chat model interface, supports streaming Chatbots, intelligent assistants
EmbeddingModel Text vectorization, connects to various vector DBs RAG retrieval, similarity matching
Tool Calling Exposes Java methods for LLM invocation Query weather, query DB, send email
AiServices Declaratively define AI services, one line of code Rapid AI application prototyping
MCP Multi-chain protocol Multi-step complex task orchestration

LangChain4j's support for RAG is particularly strong, with built-in adapters for 30+ vector databases.

This means you don't need to worry about what vector library is used underneath — PgVector, Milvus, Elasticsearch, all can be connected.

Code Example: Declaring an AI Service with AiServices

// Step 1: Define an interface, declare what you want the AI to do
public interface Assistant {
    String chat(@UserMessage String message);
}

// Step 2: Let AiServices implement this interface for you
Assistant assistant = AiServices.builder(Assistant.class)
        .chatLanguageModel(OpenAiChatModel.withApiKey("sk-xxx"))
        .build();

// Step 3: Call directly
String reply = assistant.chat("What is the working principle of ConcurrentHashMap in Java?");
System.out.println(reply);

See that?

You only need to define an interface, and AiServices automatically handles model invocation, message construction, and response parsing.

This is the "declarative" power of LangChain4j — treating AI services like ordinary Java interfaces.

2.2 LangGraph4j — Process Engine + State Machine

The core problem LangGraph4j focuses on is: "How to process-ify and state-ify the decision-making and actions of multiple AI agents."

Its design philosophy is graph as code, state as shared memory, node as agent behavior. There are three core concepts:

① State — Shared Notebook

LangGraph4j forces all agents to work around a shared AgentState object. This State is not an ordinary Map, but a data object with type safety, change tracking, and immutable snapshot capabilities.

// This is your shared notebook! All nodes rely on it to store, read, and pass data
class MyState extends AgentState {
    String userQuestion;      // What the user asked
    String weatherInfo;       // Weather result found
    String aiAnswer;          // AI's final answer
    List<String> toolCalls;   // List of tools to call
}

The design of State greatly simplifies data passing between multiple nodes — nodes don't talk directly to each other, they only read and write this notebook, and downstream nodes naturally get the processing results of upstream nodes.

② StateGraph — Executable Flowchart

StateGraph is the core abstraction of LangGraph4j: you draw a flowchart on paper, write node logic, draw arrows, and it compiles it into a "runnable program."

// Build a three-step Agent workflow: Think → Act → Answer
StateGraph<MyState> graph = new StateGraph<>(MyState.class)
        .addNode("think", this::thinkNode)      // Think node: call LLM to analyze intent
        .addNode("act", this::actNode)          // Act node: execute tool calls
        .addNode("answer", this::answerNode)    // Answer node: generate final answer
        // Conditional edge: decide which path to take next based on State
        .addConditionalEdges("think", this::routeAfterThink)
        .addEdge("act", "answer")
        .addEdge("answer", END);

// Conditional routing function — look at the notebook, decide the next step
private String routeAfterThink(MyState state) {
    if (state.toolCalls != null && !state.toolCalls.isEmpty()) {
        return "act";  // Tools to call → go to act node
    }
    return "answer";   // None → answer directly
}

The "conditional edge" here is the soul of the entire framework. It's not a static configuration, but a dynamically computable routing logic — the data in the State determines which node to go to next.

③ Checkpointing — No Fear of System Crashes

This is the most "life-saving" feature of LangGraph4j in production environments.

After each State update, the framework automatically serializes the full state and execution context (including token consumption, duration, node ID, timestamp) to persistent storage.

If the system crashes, you can precisely recover to the last successful checkpoint and retry the failed node, rather than rerunning the entire chain.

3. Understanding the Differences with an Example

3.1 Building a Simple Agent with LangChain4j

To build a simple Agent that can call tools, LangChain4j's code is very concise:

// Step 1: Define a tool (Java method + annotation)
public class WeatherTool {
    @Tool("Get the current weather for a city")
    String getWeather(@P("City Name") String city) {
        // In a real scenario, this would call a weather API
        return city + " today 25°C, sunny";
    }
}

// Step 2: Build the Agent
ChatLanguageModel model = OpenAiChatModel.builder()
        .apiKey("sk-xxx")
        .build();

Agent agent = Agent.builder(model)
        .tools(new WeatherTool())
        .build();

// Step 3: Execute
String response = agent.execute("What's the weather like in Beijing today?");
System.out.println(response);
// Output: Beijing today 25°C, sunny

The simplicity of LangChain4j lies in this: one @Tool annotation + a few lines of configuration, and the model automatically recognizes "need to check weather" and calls your Java method.

3.2 Building a Conditional Multi-Agent with LangGraph4j

When the scenario becomes complex — for example, needing to analyze intent first, then decide which sub-process to take, and retry if the result is unsatisfactory — LangGraph4j comes into play:

// Define shared state
class CodeReviewState extends AgentState {
    String prDescription;          // PR description
    String codeContent;            // Code content
    String reviewResult;           // Review result
    int reviewAttempts;            // Retry count
    boolean needsImprovement;      // Whether improvement is needed
}

// Build the review graph
StateGraph<CodeReviewState> graph = new StateGraph<>(CodeReviewState.class)
        .addNode("analyze", this::analyzePr)        // Analyze PR
        .addNode("review", this::reviewCode)        // Review code
        .addNode("improve", this::suggestFix)       // Suggest fix
        .addNode("approve", this::approve)          // Approve merge
        .addConditionalEdges("review", state -> {
            if (state.reviewResult.contains("critical issue")) {
                return "improve";    // Has issues → improve
            }
            return "approve";         // No issues → approve
        })
        .addEdge("improve", "review")                // After improvement, re-review (loop!)
        .build();

This example demonstrates the core advantages of LangGraph4j:

3.3 Summarizing the Differences in One Sentence

Scenario Use LangChain4j Use LangGraph4j
"Give the model a prompt, let it answer" ✅ Extremely simple ❌ Over-engineered
"One agent + a few tools" ✅ Just right ⚠️ Slightly heavy
"Multi-step decision + conditional branching" ⚠️ Requires manual state management ✅ Native support
"Multi-agent collaboration + long process + breakpoint recovery" ❌ Hard to implement ✅ Design goal

You may have also noticed — LangChain4j manages "how to make a single AI call elegant," while LangGraph4j manages "how dozens of agents coordinate to complete an entire business process." They are complementary, not opposing.

4. Unique Advantages of LangGraph4j

If LangChain4j is a weapon for "individual combat," then LangGraph4j is the general headquarters for "multi-branch coordination."

Beyond the branching and loop control seen above, LangGraph4j also provides several extremely powerful multi-agent collaboration modes:

Supervisor Pattern: A master Agent decides which expert Agent to assign a task to for execution. The master Agent analyzes user intent, calls the appropriate Worker Agent, and processes sub-tasks in parallel.

Fan-out Pattern: Distributes the same task to multiple sub-Agents for parallel processing, then aggregates all results. This pattern is very valuable for "multi-perspective analysis" or "cross-source verification."

Human-in-the-Loop: Automatically pauses when a node executes a sensitive step, pushes the state for human approval, waits for a human response, and then continues the subsequent process. LangGraph4j has built-in native support for this pattern.

Checkpointing + Time Travel: Supports breakpoint recovery and time-travel debugging — you can backtrack to any historical checkpoint, analyze the State at that time, and locate LLM hallucinations or logic errors.

Besides these, LangGraph4j has even more advanced capabilities:

5. Comprehensive Pros and Cons Comparison

LangChain4j Advantages

LangChain4j Limitations

LangGraph4j Advantages

LangGraph4j Limitations

6. Latest Version Status in 2026

As of the first half of 2026, both frameworks are under active development:

Framework Latest Version Release Date Main Updates
LangChain4j 1.11.0 2026-02-04 Enhanced multi-model support, RAG optimization, MCP module improvement
LangGraph4j 1.7.10 / 1.8-beta 2026-01 Hooks mechanism, async nodes, parallel execution optimization, Checkpointing enhancement

LangChain4j's version updates lean more towards feature completion, while LangGraph4j is gradually moving towards a stable production-level roadmap.

7. All Differences at a Glance

Comparison Dimension LangChain4j LangGraph4j
Core Positioning AI capability access layer — "Parts Box" Agent workflow orchestration layer — "Blueprint"
Core Abstractions ChatModel, AiServices, Tool StateGraph, Node, Edge, Checkpoint
State Management None built-in, self-maintained Mandatory AgentState, type-safe, versioned, traceable
Conditional Routing Limited if-else logic Conditional edges, supports complex dynamic routing
Loop Support Limited recursion Native loop edges, Turing-complete
Multi-Agent Collaboration Basic multi-instance invocation Supervisor + Worker + Fan-out + HITL
Breakpoint/Checkpoint None Built-in, supports Redis/PostgreSQL persistence
Concurrent Execution Requires manual orchestration Native parallel nodes, edges
Model Support 20+ types, unified interface Framework-agnostic, depends on LangChain4j or Spring AI
Learning Curve Low Medium to high
Version Maturity High (1.11.0) Medium (1.7.10)
Gradle/Maven Integration Mature Mature
Spring Boot Integration Native support Supported via adapter module
Visualization Support Average Generates interactive graphs based on Graphviz

8. Applicable Scenarios

LangChain4j Alone is Sufficient

Scenario Typical Application
Intelligent customer service / FAQ Q&A Intent recognition + knowledge base Q&A
RAG knowledge base retrieval Document Q&A, enterprise internal knowledge assistant
Single Agent + Tool calling Subscription email sending, notification query, simple CRUD tasks
Rapid prototype validation Validate AI ideas within a week, proof of concept
Scenarios requiring fine control, low coupling Existing complex systems, only need to introduce AI capabilities in a small scope

For these scenarios, LangChain4j's out-of-the-box capabilities + low learning curve are a complete advantage.

LangGraph4j is Needed for Strong Entry

Scenario Typical Application
Complex multi-turn decision + multi-agent collaboration Code review multi-agent system, supply chain intelligent scheduling
Long process approval + human-machine collaboration Project review system, high-risk SQL approval, financial order review
Long-cycle tasks requiring breakpoint recovery Public opinion monitoring agent (may run for hours or even days)
Multiple Agents executing in parallel + phased summarization Multi-perspective analysis, cross-source information verification
Migrating from Python LangGraph Keep the same graph orchestration logic, switch tech stack to Java

In these scenarios, the capabilities provided by LangGraph4j are very difficult to achieve with LangChain4j alone.

Best Practice Combination

The most elegant solution is never "choose one." In actual projects, LangChain4j + LangGraph4j is a very common combination:

LangGraph4j's official roadmap also follows this idea: provide framework-agnostic core abstractions, and adapt to the interface specifications of LangChain4j and Spring AI respectively through adapter modules.

That is to say, regardless of whether you use LangChain4j or Spring AI underneath, the graph orchestration logic is the same, and switching the underlying layer does not require changing the graph.

More project practices on my technical website: susan.net.cn/project

9. Quick Start

LangChain4j

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>1.11.0</version>
</dependency>

LangGraph4j

<dependency>
    <groupId>org.bsc.langgraph4j</groupId>
    <artifactId>langgraph4j-core</artifactId>
    <version>1.7.10</version>
</dependency>
<!-- Integration with LangChain4j -->
<dependency>
    <groupId>org.bsc.langgraph4j</groupId>
    <artifactId>langgraph4j-langchain4j</artifactId>
    <version>1.7.10</version>
</dependency>

10. Final Words

Writing up to here, I want to summarize in one sentence: LangChain4j lets you "integrate large models into Java," LangGraph4j lets you "elegantly orchestrate multiple AI agents."

They have never been a "choose one" relationship, but a collaborative relationship at different levels.

LangChain4j is the AI capability access layer — giving you model APIs, vector retrieval, Tool Calling; LangGraph4j is the process orchestration layer — giving you state graphs, conditional routing, checkpoint recovery.

One is "how to connect," the other is "how to orchestrate."

The correct posture for technology selection is not to ask "which is better," but to ask yourself three questions:

  1. How many decision steps does my business need? 1-3 steps, LangChain4j is sufficient; multi-step + branching + loops, LangGraph4j enters the scene.
  2. Do my Agents need to collaborate with each other? Single Agent uses LangChain4j; multi-Agent uses LangGraph4j's Supervisor mode.
  3. In my task flow, can everything be rerun after a failure? Lightweight tasks don't need it; long-cycle tasks + breakpoint recovery, LangGraph4j's checkpoint mechanism is almost irreplaceable.

The evolution path from light to heavy is very clear: ChatModel single call → AiServices declarative service → Tool-calling single Agent → Multi-step conditional chain → LangGraph4j graph orchestration.

Knowing when to upgrade tools and when to keep things simple is itself part of architectural capability.

I hope this article helps you no longer feel confused when facing these two frameworks.