Artificial Intelligence is changing how we build software applications. Modern applications can do more than answer questions: they can also use tools, call APIs, and execute operations through application code.
In this tutorial, we will build a simple AI agent using Java, Spring Boot, LangChain4j, and OpenAI. Our agent will understand natural-language questions and use Java calculator methods to perform addition and multiplication when appropriate.
By the end of this tutorial, you will understand how to connect an AI model to Java methods and expose the assistant through a REST API.
What We Will Build
We will create a calculator AI agent that accepts questions such as:
- What is 125 plus 375?
- What is 24 multiplied by 6?
The application will receive the question through a Spring Boot REST endpoint, send it to the AI assistant, allow the model to request a calculator tool call, and return the assistant’s response as JSON.
Technologies Used
- Java 17: Programming language.
- Spring Boot 3.3.5: Application framework.
- Maven: Dependency management and project build.
- LangChain4j 0.36.2: AI integration and tool-calling support.
- OpenAI: Language model provider.
- Postman or curl: Testing the REST API.
These are the versions used in this example. Verify compatibility and test the complete project in your environment before deploying it.
1. How Does an AI Agent Work?
A traditional chatbot primarily responds to user messages. An AI agent can also request that external tools perform specific operations.
For example, when a user asks, “What is 125 plus 375?”, the model can request the Java add() method. LangChain4j coordinates the tool call, the Java application executes the method, and the result can be returned to the model to formulate the final response.
The important distinction is that the model requests the operation; your Java application executes it.
2. Project Architecture
The application has five main parts:
- REST Controller: Receives the user’s question.
- Assistant Interface: Defines how the application interacts with the AI assistant.
- AI Configuration: Connects the language model and calculator tools.
- Calculator Tools: Contains the Java methods for arithmetic.
- Response DTO: Returns the answer in JSON format.
The request follows this flow:
User → Spring Boot REST API → LangChain4j Assistant → OpenAI Model → Java Calculator Tool (when requested) → Assistant Response → User.
3. Create the Spring Boot Project
Create a Maven-based Spring Boot project with Java 17.
Use the following project structure:
java-springboot-ai-agent/
├── pom.xml
└── src/main/
├── java/com/pixeltrice/agent/
│ ├── JavaAiAgentApplication.java
│ ├── assistant/Assistant.java
│ ├── config/AiConfig.java
│ ├── tools/CalculatorTools.java
│ └── api/
│ ├── AgentController.java
│ ├── ChatRequest.java
│ └── ChatResponse.java
└── resources/application.properties4. Add the Maven Dependencies
Open pom.xml and add the following configuration:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.pixeltrice</groupId>
<artifactId>java-springboot-ai-agent</artifactId>
<version>0.0.1-SNAPSHOT</version>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.3.5</version>
<relativePath/>
</parent>
<properties>
<java.version>17</java.version>
<langchain4j.version>0.36.2</langchain4j.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j</artifactId>
<version>${langchain4j.version}</version>
</dependency>
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai</artifactId>
<version>${langchain4j.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>Here is what the dependencies provide:
spring-boot-starter-webcreates REST APIs.langchain4jprovides core AI integration functionality.langchain4j-open-aiintegrates LangChain4j with OpenAI.spring-boot-starter-validationvalidates incoming requests.spring-boot-starter-testprovides testing libraries.
5. Create the Main Application Class
Create JavaAiAgentApplication.java:
package com.pixeltrice.agent;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class JavaAiAgentApplication {
public static void main(String[] args) {
SpringApplication.run(
JavaAiAgentApplication.class, args);
}
}The @SpringBootApplication annotation enables Spring Boot’s main application configuration and component scanning.
The main() method is the entry point of the application. SpringApplication.run() initializes Spring and starts the embedded web server.
6. Implement the Calculator Tools
Create CalculatorTools.java inside the tools package:
package com.pixeltrice.agent.tools;
import dev.langchain4j.agent.tool.Tool;
import org.springframework.stereotype.Component;
@Component
public class CalculatorTools {
@Tool("Add two numbers and return their sum.")
public double add(double a, double b) {
return a + b;
}
@Tool("Multiply two numbers and return their product.")
public double multiply(double a, double b) {
return a * b;
}
}The @Component annotation allows Spring to manage the calculator class as a bean.
The @Tool annotations describe the available operations to LangChain4j. These descriptions help the model determine when a method is relevant.
The add() method adds two numbers, while multiply() multiplies them.
For example:
add(125, 375); // Returns 500.0
multiply(24, 6); // Returns 144.0The calculations themselves are performed by Java, not by the AI model.
7. Define the AI Assistant
Create Assistant.java inside the assistant package:
package com.pixeltrice.agent.assistant;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
public interface Assistant {
@SystemMessage("""
You are a helpful assistant for a calculator demo.
Use the provided calculator tools for arithmetic
when appropriate.
Keep your answers concise.
Do not claim a tool was used unless it was called.
""")
String chat(@UserMessage String message);
}This interface defines the contract for our AI assistant.
The @SystemMessage annotation supplies instructions about the assistant’s role and behavior. The @UserMessage annotation marks the incoming question as user input.
LangChain4j will create an implementation of this interface when we configure AiServices in the next step.
8. Configure OpenAI and LangChain4j
Create AiConfig.java inside the config package:
package com.pixeltrice.agent.config;
import com.pixeltrice.agent.assistant.Assistant;
import com.pixeltrice.agent.tools.CalculatorTools;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class AiConfig {
@Bean
public OpenAiChatModel chatModel() {
String apiKey = System.getenv("OPENAI_API_KEY");
if (apiKey == null || apiKey.isBlank()) {
throw new IllegalStateException(
"OPENAI_API_KEY environment variable is missing."
);
}
return OpenAiChatModel.builder()
.apiKey(apiKey)
.modelName("gpt-4o-mini")
.build();
}
@Bean
public Assistant assistant(
OpenAiChatModel chatModel,
CalculatorTools calculatorTools) {
return AiServices.builder(Assistant.class)
.chatLanguageModel(chatModel)
.tools(calculatorTools)
.build();
}
}The @Configuration annotation marks this class as a source of Spring bean definitions.
The chatModel() method creates the OpenAI client. It reads the API key from the OPENAI_API_KEY environment variable rather than storing the secret in source code.
The AiServices.builder(Assistant.class) call creates the assistant implementation. The chatLanguageModel() method connects the language model, and tools() registers the calculator tools.
This configuration brings the model and Java methods together.
9. Create the Request and Response Classes
ChatRequest.java
package com.pixeltrice.agent.api;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
public record ChatRequest(
@NotBlank(message = "Message must not be blank")
@Size(
max = 2000,
message = "Message must be 2000 characters or fewer"
)
String message
) {}ChatRequest is a Java record that stores the incoming message.
@NotBlank rejects missing or whitespace-only messages, and @Size limits the message to 2,000 characters. These validation rules are enforced when the controller processes the request with @Valid.
ChatResponse.java
package com.pixeltrice.agent.api;
public record ChatResponse(String answer) {
}This record represents the API response. The answer field contains the text returned by the assistant.
Spring Boot automatically serializes the record into JSON.
10. Create the REST Controller
Create AgentController.java inside the api package:
package com.pixeltrice.agent.api;
import com.pixeltrice.agent.assistant.Assistant;
import jakarta.validation.Valid;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/agent")
public class AgentController {
private final Assistant assistant;
public AgentController(Assistant assistant) {
this.assistant = assistant;
}
@PostMapping("/chat")
public ChatResponse chat(
@Valid @RequestBody ChatRequest request) {
String answer = assistant.chat(request.message());
return new ChatResponse(answer);
}
}The @RestController annotation identifies this class as a REST controller.
The @RequestMapping("/api/agent") annotation defines the base URL. The @PostMapping("/chat") annotation adds the chat endpoint.
The @RequestBody annotation converts the incoming JSON into a ChatRequest object, while @Valid triggers its validation rules.
The controller then passes the message to the assistant and wraps the returned text in a ChatResponse.
11. Configure the Application
In src/main/resources/application.properties, add:
spring.application.name=pixeltrice-java-ai-agent
server.port=8080The first property sets the application name. The second configures the embedded web server to use port 8080.
12. Run the Application
Before starting the application, set your OpenAI API key.
macOS or Linux:
export OPENAI_API_KEY="your-api-key-here"Windows PowerShell:
$env:OPENAI_API_KEY="your-api-key-here"Replace the placeholder with your actual API key. Never commit the key to a public repository.
From the project root, run:
mvn spring-boot:runWait for Spring Boot to finish starting. Maven must be installed, and the project must use a compatible Java version.
13. Test the AI Agent Using Postman
Send an HTTP POST request to:
http://localhost:8080/api/agent/chatChoose Body → raw → JSON in Postman and enter:
{
"message": "What is 125 plus 375?"
}A successful response might look like:
{
"answer": "500"
}The exact wording may vary.
Now test multiplication:
{
"message": "What is 24 multiplied by 6?"
}The expected numeric answer is 144.
You can also test the endpoint using curl:
curl -X POST http://localhost:8080/api/agent/chat \
-H "Content-Type: application/json" \
-d '{"message":"What is 125 plus 375?"}'14. Verify That Tool Calling Actually Occurs
A correct answer does not necessarily mean the model called a Java tool. It may calculate the result itself.
If you want to demonstrate agent tool calling accurately, inspect the model and application logs, or add explicit logging around the calculator methods. Confirm that add() or multiply() actually executed for the test request.
This is important when explaining the difference between a chatbot that answers questions and an AI agent that can use tools.
15. Important Considerations for Production
This project is an educational demonstration, not a production-ready service.
Before exposing it to real users, consider adding:
- Authentication and authorization.
- Rate limiting and request timeouts.
- Stronger error handling and input validation.
- Monitoring and structured logging.
- Secure API key management.
- Appropriate limits on model usage and spending.
Also remember that an LLM can produce incorrect or unexpected responses. Do not assume every response is correct just because it is returned successfully.
Conclusion
In this tutorial, we built a simple AI agent using Java, Spring Boot, LangChain4j, and OpenAI.
We created calculator tools, registered them with the assistant, exposed a REST endpoint, and tested the application using Postman.
The most important concept is that the AI model can request an operation, while the Java application executes the registered tool and returns its result.
You can extend this foundation by adding more tools, connecting the agent to external APIs, or building an assistant that interacts with other services.
If you found this tutorial helpful, explore more Java and Spring Boot tutorials on PixelTrice.
Happy Coding!
