How langchain4j/langchain4j-spring works
1. This repository is a multi-module Maven monorepo of Spring Boot starters for LangChain4j integrations. Its purpose is to expose LangChain4j building blocks as auto-configured Spring beans, so application code can assemble AI services, models, and stores with minimal wiring.
2. The codebase is split into two parallel compatibility tracks:
- “spring-boot-starter” modules for the older Spring Boot line
- “spring-boot4-starter” modules for the newer Spring Boot 4 line
The duplication is intentional: each integration keeps its own auto-configuration and property classes per Boot generation, while preserving a similar package/module structure.
3. The central architectural layer is langchain4j-spring-boot-starter and langchain4j-spring-boot4-starter. These provide the top-level LangChain4j auto-configuration plus the AI service orchestration layer:
- LangChain4jAutoConfig/AutoConfiguration
- AiServicesAutoConfig/AutoConfiguration
- scanning, wiring, and registration of @AiService interfaces
- event publication such as AiServiceRegisteredEvent
This is the core boundary between Spring’s bean lifecycle and LangChain4j’s runtime service creation.
4. The AI service subsystem is responsible for turning annotated interfaces into usable service proxies. It includes:
- classpath scanning for candidate interfaces
- wiring mode selection for automatic vs explicit configuration
- construction of service proxies via an AiServiceFactory
- support for chat models, streaming models, tools, chat memory, retrieval augmentors, and structured output
The test tree shows many scenario-specific integration tests, indicating these are key behavior boundaries and not just helper utilities.
5. Retrieval-Augmented Generation is modeled as a separate but connected subsystem. There are dedicated starters for:
- langchain4j-rag / langchain4j-easy-rag
- retrieval and document/ingestion configuration
These sit upstream of AI services: documents are ingested, retrieved content is prepared, and then injected into service execution through retrieval augmentors/content retrievers.
6. Model provider integrations are organized as one starter per vendor, with near-uniform internal structure. Examples include:
- OpenAI / OpenAI Official
- Azure OpenAI
- Anthropic
- Google Gemini / Vertex AI Gemini
- Mistral AI
- Ollama
- GitHub Models
- Voyage AI
Each module generally contains:
- a vendor-specific auto-configuration class
- a root properties class
- nested model-specific properties for chat, embedding, image, moderation, scoring, function calling, or language models
Architecturally, these modules adapt vendor APIs into LangChain4j model abstractions.
7. Vector store and embedding store integrations are another major subsystem. There are starters for:
- Elasticsearch
- Milvus
- Azure Cosmos DB NoSQL
- Azure Cosmos DB Mongo VCore
- Azure AI Search
These modules expose embedding store beans and vendor/client configuration so retrieval and persistence layers can store vectors or search indexed embeddings. They are downstream of embedding models and upstream of RAG/retrieval flows.
8. The HTTP client layer is separated as a reusable adapter module:
- langchain4j-http-client-spring-restclient
- langchain4j-http-client-spring-boot4-restclient
These provide a Spring-based HttpClientBuilderFactory implementation via Java service loading (META-INF/services), letting LangChain4j use Spring’s REST client infrastructure without each model starter reimplementing HTTP concerns.
9. The langchain4j-reactor module is a small but important reactive bridge. It adapts token streams into Reactor Flux via TokenStreamToFluxAdapter, also exposed through service-provider registration. This makes streaming AI output compatible with reactive Spring applications.
10. Each starter follows the same mechanical pattern:
- a package-scoped auto-configuration class
- one root properties holder plus nested per-capability property classes
- META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports for Spring Boot auto-discovery
- integration tests that load a Spring context and verify the wiring
This consistency is what makes the architecture diagram easy to reason about: same pattern, different integration targets.
11. The test modules are not incidental; they act as executable architecture documentation. They cover auto-configuration, container-backed integrations, streaming, tool injection, conflicting bean scenarios, package scanning, and multiple service wiring modes. Several integration tests imply external dependencies such as Elasticsearch, and the repo uses Spring Boot test support heavily.
12. Build and delivery are managed at the monorepo level. The root pom.xml, Maven wrapper, and GitHub Actions workflows handle:
- CI validation
- release and snapshot publishing
- version update automation
This supports a publishable starter ecosystem rather than a single application runtime.
13. In an architecture diagram, the main flow is: application code declares Spring properties and @AiService interfaces → Spring Boot auto-configures provider clients/models/stores → LangChain4j service factories assemble proxies and retrieval/tooling components → requests flow to external AI/vector/search services → streaming/reactive adapters and events integrate results back into the app.
14. The key boundary to emphasize is that this repo does not implement AI features itself; it wires LangChain4j abstractions into Spring Boot conventions. Vendor modules own provider-specific configuration, while the core starter owns service discovery and orchestration across all integrations.
Main entry points: AiServicesAutoConfig.java AI Services · RagAutoConfig.java RAG · AiServicesAutoConfiguration.java AI Services 4 · TokenStreamToFluxAdapter.java Reactor Bridge
Components 27
Monorepo
Maven multi-module starter ecosystem and delivery wiring
- Root POM · Aggregates all starter modules and manages release packaging
pom.xml - Maven Wrapper · Pinned Maven bootstrap for local and CI builds
mvnw - CI Workflows · Validation, release, snapshot publishing, and version automation
.github/workflows/main.yaml
Core Spring
Shared LangChain4j service orchestration and RAG wiring
- Spring Boot 3 · Auto-configuration boundary for LangChain4j services and RAG
langchain4j-spring-boot-starter/src/main/java/dev/langchain4j/spring/LangChain4jAutoConfig.java - Spring Boot 4 · Boot 4 variant of the LangChain4j core orchestration layer
langchain4j-spring-boot4-starter/src/main/java/dev/langchain4j/spring/LangChain4jAutoConfiguration.java - AI Services · Scans @AiService interfaces and assembles service proxies
langchain4j-spring-boot-starter/src/main/java/dev/langchain4j/service/spring/AiServicesAutoConfig.java - AI Services 4 · Boot 4 AI service scanner and proxy factory wiring
langchain4j-spring-boot4-starter/src/main/java/dev/langchain4j/service/spring/AiServicesAutoConfiguration.java - RAG · Retrieval augmentation and ingestion properties for service execution
langchain4j-spring-boot-starter/src/main/java/dev/langchain4j/rag/spring/RagAutoConfig.java - RAG 4 · Boot 4 retrieval augmentation configuration
langchain4j-spring-boot4-starter/src/main/java/dev/langchain4j/rag/spring/RagAutoConfiguration.java
Model Starters
Vendor adapters that expose chat, embedding, image, moderation, and scoring beans
- OpenAI · OpenAI chat, embedding, image, language, and moderation properties
langchain4j-open-ai-spring-boot-starter/src/main/java/dev/langchain4j/openai/spring/AutoConfig.java - OpenAI 4 · Boot 4 OpenAI integration and model properties
langchain4j-open-ai-spring-boot4-starter/src/main/java/dev/langchain4j/openai/spring/OpenAiAutoConfiguration.java - Azure OpenAI · Azure OpenAI chat, embedding, and image wiring
langchain4j-azure-open-ai-spring-boot-starter/src/main/java/dev/langchain4j/azure/openai/spring/AutoConfig.java - Anthropic · Anthropic chat model properties and auto-configuration
langchain4j-anthropic-spring-boot-starter/src/main/java/dev/langchain4j/anthropic/spring/AutoConfig.java - Gemini · Google AI Gemini chat, embedding, and function-calling wiring
langchain4j-google-ai-gemini-spring-boot-starter/src/main/java/dev/langchain4j/googleaigemini/spring/AutoConfig.java - Mistral AI · Mistral chat, embedding, fim, and moderation wiring
langchain4j-mistral-ai-spring-boot-starter/src/main/java/dev/langchain4j/mistralai/spring/AutoConfig.java - Ollama · Local Ollama chat, embedding, and language model properties
langchain4j-ollama-spring-boot-starter/src/main/java/dev/langchain4j/ollama/spring/AutoConfig.java - GitHub Models · GitHub Models chat and embedding integration
langchain4j-github-models-spring-boot-starter/src/main/java/dev/langchain4j/model/githubmodels/spring/AutoConfig.java - Vertex Gemini · Vertex AI Gemini chat integration
langchain4j-vertex-ai-gemini-spring-boot-starter/src/main/java/dev/langchain4j/vertexai/gemini/spring/AutoConfig.java - Voyage AI · Voyage embedding and scoring model wiring
langchain4j-voyage-ai-spring-boot-starter/src/main/java/dev/langchain4j/voyageai/spring/AutoConfig.java
Storage Starters
Embedding store and retrieval backends for vector persistence and search
- Elasticsearch Store · Embedding store backed by Elasticsearch client configuration
langchain4j-elasticsearch-spring-boot-starter/src/main/java/dev/langchain4j/store/embedding/elasticsearch/spring/ElasticsearchEmbeddingStoreAutoConfiguration.java - Milvus Store · Milvus-backed vector persistence starter
langchain4j-milvus-spring-boot-starter/src/main/java/dev/langchain4j/store/embedding/milvus/spring/MilvusEmbeddingStoreAutoConfiguration.java - Cosmos NoSQL · Azure Cosmos DB NoSQL embedding store integration
langchain4j-azure-cosmos-nosql-spring-boot-starter/src/main/java/dev/langchain4j/store/embedding/azure/cosmos/nosql/spring/AzureCosmosDbNoSqlEmbeddingStoreAutoConfiguration.java - Cosmos Mongo · Azure Cosmos DB Mongo VCore embedding store integration
langchain4j-azure-cosmos-mongo-vcore-spring-boot-starter/src/main/java/dev/langchain4j/store/embedding/azure/cosmos/mongo/vcore/spring/AzureCosmosDbMongoVCoreEmbeddingStoreAutoConfiguration.java - Azure AI Search · Search-backed retrieval and embedding storage starter
langchain4j-azure-ai-search-spring-boot-starter/src/main/java/dev/langchain4j/azure/aisearch/spring/AutoConfig.java
Adapters
Reusable HTTP and reactive bridges used by starters and applications
- Spring RestClient · Spring REST client adapter loaded through service provider registration
langchain4j-http-client-spring-restclient/src/main/java/dev/langchain4j/http/client/spring/restclient/SpringRestClientBuilderFactory.java - Spring RestClient 4 · Boot 4 REST client adapter for LangChain4j HTTP clients
langchain4j-http-client-spring-boot4-restclient/src/main/java/dev/langchain4j/http/client/spring/restclient/SpringRestClientBuilderFactory.java - Reactor Bridge · Converts token streams into Reactor Flux for streaming apps
langchain4j-reactor/src/main/java/dev/langchain4j/reactor/TokenStreamToFluxAdapter.java
Connections 34
- Root POM → Spring Boot 3: builds · Root reactor includes the Boot 3 core starter
- Root POM → Spring Boot 4: builds · Root reactor includes the Boot 4 core starter
- Root POM → CI Workflows: delivers · CI and release workflows publish artifacts
- Spring Boot 3 → AI Services: orchestrates · Core starter enables AI service scanning and proxy creation
- Spring Boot 3 → RAG: provides · Core starter exposes retrieval augmentation wiring
- Spring Boot 4 → AI Services 4: orchestrates · Boot 4 core starter enables AI service scanning and proxy creation
- Spring Boot 4 → RAG 4: provides · Boot 4 core starter exposes retrieval augmentation wiring
- AI Services → OpenAI: uses models · AI services consume vendor model beans
- AI Services → Anthropic: uses models · AI services consume vendor model beans
- AI Services → Gemini: uses models · AI services consume vendor model beans
- AI Services → Mistral AI: uses models · AI services consume vendor model beans
- AI Services → Ollama: uses models · AI services consume vendor model beans
- AI Services → GitHub Models: uses models · AI services consume vendor model beans
- AI Services → Vertex Gemini: uses models · AI services consume vendor model beans
- AI Services → Voyage AI: uses models · AI services can use scoring and embedding support
- AI Services → Elasticsearch Store: retrieves from · Retrieval augmentors can consult embedding stores
- AI Services → Azure AI Search: retrieves from · Retrieval augmentors can consult search-backed stores
- AI Services → Reactor Bridge: streams via · Streaming AI service output can be bridged to Reactor
- AI Services 4 → OpenAI 4: uses models · Boot 4 AI services consume vendor model beans
- AI Services 4 → Azure OpenAI: uses models · Boot 4 AI services consume vendor model beans
- AI Services 4 → Reactor Bridge: streams via · Streaming AI service output can be bridged to Reactor
- RAG → Elasticsearch Store: indexes into · RAG ingestion persists vectors in stores
- RAG → Milvus Store: indexes into · RAG ingestion persists vectors in stores
- RAG → Cosmos NoSQL: indexes into · RAG ingestion persists vectors in stores
- RAG → Cosmos Mongo: indexes into · RAG ingestion persists vectors in stores
- RAG → Azure AI Search: indexes into · RAG can use search as a retrieval backend
- RAG 4 → Elasticsearch Store: indexes into · Boot 4 RAG ingestion persists vectors in stores
- RAG 4 → Azure AI Search: indexes into · Boot 4 RAG can use search as a retrieval backend
- Spring RestClient → OpenAI: supports · Shared HTTP adapter is reused by provider clients
- Spring RestClient → Anthropic: supports · Shared HTTP adapter is reused by provider clients
- Spring RestClient 4 → OpenAI 4: supports · Boot 4 HTTP adapter is reused by provider clients
- Spring RestClient 4 → Azure OpenAI: supports · Boot 4 HTTP adapter is reused by provider clients
- Reactor Bridge → AI Services: adapts · Reactive token streaming feeds AI service consumers
- Reactor Bridge → AI Services 4: adapts · Reactive token streaming feeds AI service consumers