LangGraph Java Integration

Use LangGraph4j with Oracle AI Database to persist workflow state and inspect execution history from Java applications.

The langgraph4j-oracle-saver module provides OracleSaver, a checkpoint saver that stores LangGraph4j workflow state in Oracle Database 23ai.

Contents

Review Requirements

Use the LangGraph4j Oracle saver with the following runtime requirements:

Add the Dependency

Add the LangGraph4j Oracle saver module to your Maven build.

<dependency>
    <groupId>org.bsc.langgraph4j</groupId>
    <artifactId>langgraph4j-oracle-saver</artifactId>
    <version>1.7.0</version>
</dependency>

For Gradle, add the module as an implementation dependency.

implementation 'org.bsc.langgraph4j:langgraph4j-oracle-saver:1.7.0'

Use the module version that matches the rest of your LangGraph4j dependencies.

Configure the Oracle Data Source

Create an OracleDataSource and include the Jackson JSON provider parameter in the JDBC URL.

OracleDataSource dataSource = new OracleDataSource();
dataSource.setURL(
    "jdbc:oracle:thin:@localhost:1521/FREEPDB1?oracle.jdbc.provider.json=jackson-json-provider"
);
dataSource.setUser("scott");
dataSource.setPassword("tiger");

For production applications, use secure credential handling and a connection pool that matches your application server or runtime.

Initialize OracleSaver

Create OracleSaver with a data source and schema create option.

OracleSaver saver = OracleSaver.builder()
    .createOption(CreateOption.CREATE_IF_NOT_EXISTS)
    .dataSource(dataSource)
    .build();

OracleSaver stores workflow checkpoints in Oracle AI Database so workflow state can survive application restarts and system failures.

Compile a Graph with Checkpoint Persistence

Pass OracleSaver to the LangGraph4j compile configuration.

import oracle.jdbc.pool.OracleDataSource;
import org.bsc.langgraph4j.CompileConfig;
import org.bsc.langgraph4j.CompiledGraph;
import org.bsc.langgraph4j.RunnableConfig;
import org.bsc.langgraph4j.StateGraph;
import org.bsc.langgraph4j.action.NodeAction;
import org.bsc.langgraph4j.checkpoint.CreateOption;
import org.bsc.langgraph4j.checkpoint.OracleSaver;
import org.bsc.langgraph4j.state.AgentState;

import java.util.Map;
import java.util.Optional;

import static org.bsc.langgraph4j.StateGraph.END;
import static org.bsc.langgraph4j.StateGraph.START;
import static org.bsc.langgraph4j.action.AsyncNodeAction.node_async;

OracleDataSource dataSource = new OracleDataSource();
dataSource.setURL(
    "jdbc:oracle:thin:@localhost:1521/FREEPDB1?oracle.jdbc.provider.json=jackson-json-provider"
);
dataSource.setUser("scott");
dataSource.setPassword("tiger");

OracleSaver saver = OracleSaver.builder()
    .createOption(CreateOption.CREATE_IF_NOT_EXISTS)
    .dataSource(dataSource)
    .build();

NodeAction<AgentState> agent = state -> Map.of("agent_1:prop1", "agent_1:test");

StateGraph<AgentState> graph = new StateGraph<>(AgentState::new)
    .addNode("agent_1", node_async(agent))
    .addEdge(START, "agent_1")
    .addEdge("agent_1", END);

CompileConfig compileConfig = CompileConfig.builder()
    .checkpointSaver(saver)
    .build();

RunnableConfig runnableConfig = RunnableConfig.builder().build();
CompiledGraph<AgentState> workflow = graph.compile(compileConfig);

Optional<AgentState> result = workflow.invoke(
    Map.of("input", "test1"),
    runnableConfig
);

The graph persists checkpoints as it runs. Without a checkpoint saver, workflow state remains in memory.

Inspect State History

Use getStateHistory() to inspect saved checkpoints for a workflow run.

workflow
    .getStateHistory(runnableConfig)
    .forEach(state -> System.out.println("Node: " + state.node()));

State history is available only when the workflow uses a checkpoint saver.

Release saver resources when the workflow no longer needs the saver.

saver.release(runnableConfig);

Manage Schema Creation

OracleSaver can provision the tables and indexes that it needs for checkpoint persistence.

Create Option Use
CreateOption.CREATE_IF_NOT_EXISTS Create missing checkpoint objects and preserve existing objects.
CreateOption.CREATE_OR_REPLACE Re-create checkpoint objects. Use only in development or controlled rebuild workflows.

Caution: Do not use replacement create options in production unless you intend to rebuild checkpoint storage.

Review Reference Links