LangChain4j Introduction & Architecture

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;
 
// 1. Declare what you want as an ordinary Java interface.
interface Assistant {
    String chat(String message);
}
 
public class Demo {
    public static void main(String[] args) {
 
        ChatModel model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o-mini")
                .temperature(0.2)
                .build();
 
        // 2. LangChain4j implements the interface against the model.
        Assistant assistant = AiServices.create(Assistant.class, model);
 
        // 3. Call it like any other bean.
        System.out.println(assistant.chat("Explain Java records in two sentences."));
    }
}

import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.V;
 
interface SupportAssistant {
 
    @SystemMessage("""
            You are a support agent for the Acme billing product.
            Answer only questions about Acme billing.
            Never invent prices, policies or account details.
            """)
    String answer(@UserMessage String question);
 
    @SystemMessage("You extract structured data. Output nothing but the requested fields.")
    @UserMessage("Extract the customer's intent from: {{message}}")
    Intent classify(@V("message") String message);
}

enum Sentiment { POSITIVE, NEUTRAL, NEGATIVE }
 
record Ticket(String summary, Priority priority, List<String> components) {
    enum Priority { LOW, MEDIUM, HIGH, CRITICAL }
}
 
interface Analyst {
 
    // Returns the enum directly. LangChain4j constrains the model to the
    // permitted values, so you cannot receive "VERY_POSITIVE".
    Sentiment sentimentOf(String review);
 
    // Returns a record. The JSON schema is derived from the type.
    Ticket triage(String bugReport);
 
    // Even booleans work, which makes routing logic trivial.
    boolean isSpam(String message);
}

Analyst analyst = AiServices.create(Analyst.class, model);
 
if (analyst.isSpam(message)) {
    return;
}
Ticket ticket = analyst.triage(message);

import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.service.MemoryId;
 
interface Assistant {
    // @MemoryId keeps each user's conversation separate.
    String chat(@MemoryId String userId, @UserMessage String message);
}
 
Assistant assistant = AiServices.builder(Assistant.class)
        .chatModel(model)
        // A memory per user, each bounded to 20 messages. Without a bound the
        // prompt grows on every turn until it exceeds the context window —
        // and you pay for the entire history on every single call.
        .chatMemoryProvider(userId -> MessageWindowChatMemory.withMaxMessages(20))
        .build();

import dev.langchain4j.agent.tool.Tool;
 
class BookingTools {
 
    private final BookingRepository bookings;
 
    BookingTools(BookingRepository bookings) {
        this.bookings = bookings;
    }
 
    @Tool("Look up a booking by its reference. Returns the booking details or NOT_FOUND.")
    String getBooking(String reference) {
        return bookings.findByReference(reference)
                .map(Booking::describe)
                .orElse("NOT_FOUND: no booking with reference " + reference);
    }
 
    @Tool("Cancel a booking. Only call this after the customer has explicitly confirmed.")
    String cancelBooking(String reference) {
        // Authorisation belongs here, in code — not in the prompt.
        return bookings.cancel(reference) ? "CANCELLED" : "ERROR: could not cancel";
    }
}

Assistant assistant = AiServices.builder(Assistant.class)
        .chatModel(model)
        .tools(new BookingTools(repository))
        // Cap the loop. A confused agent will otherwise retry a failing tool
        // until it exhausts your budget.
        .maxSequentialToolsInvocations(5)
        .build();

import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever;
import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore;
 
// Ingest: split, embed, store.
EmbeddingStoreIngestor.builder()
        .documentSplitter(DocumentSplitters.recursive(500, 100))
        .embeddingModel(embeddingModel)
        .embeddingStore(embeddingStore)
        .build()
        .ingest(documents);
 
// Retrieve: attach to the service and RAG happens on every call.
Assistant assistant = AiServices.builder(Assistant.class)
        .chatModel(model)
        .contentRetriever(EmbeddingStoreContentRetriever.builder()
                .embeddingStore(embeddingStore)
                .embeddingModel(embeddingModel)
                .maxResults(5)
                .minScore(0.6)          // drop weak matches
                .build())
        .build();

package com.javaagentic.demo.config;
 
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
@Configuration
public class LangChain4jConfig {
 
    @Bean
    ChatModel chatModel(@Value("${OPENAI_API_KEY}") String apiKey) {
        return OpenAiChatModel.builder()
                .apiKey(apiKey)
                .modelName("gpt-4o-mini")
                .temperature(0.2)
                .timeout(java.time.Duration.ofSeconds(60))
                .maxRetries(3)
                .build();
    }
 
    // Now injectable anywhere, like any other bean.
    @Bean
    Assistant assistant(ChatModel chatModel) {
        return AiServices.builder(Assistant.class)
                .chatModel(chatModel)
                .chatMemoryProvider(id -> MessageWindowChatMemory.withMaxMessages(20))
                .build();
    }
}