Why AI4J
AI4J is an AI SDK for Java 8+. Its core goal is to lower the cost of wiring AI into Java projects: fewer concepts to absorb, less glue code to write, less friction from provider differences, while keeping an upgrade path toward RAG, MCP, Spring Boot, Agent and Coding Agent.
This page is not a complete API tour. It answers a single question: why you might consider AI4J in a Java project.
What problem AI4J tries to solve
When a Java project first adopts AI, the first step is usually just "get one model call working". But real projects soon run into more:
- You need to integrate OpenAI-compatible endpoints, domestic model platforms, and different kinds of model capability at the same time.
- The request shapes for
Chat,Responses, streaming, multimodal, Embedding and Rerank are inconsistent. - Local tools, Skill, MCP, RAG and Memory easily end up as several disconnected codebases.
- There is no smooth upgrade path between plain Java, Spring Boot, an Agent runtime, a CLI, or a workflow platform.
- The large frameworks are fully featured, but the learning and configuration cost to complete a simple integration is high.
AI4J's trade-off: make the Java AI integration path thin and straight first, then unfold the upper-layer capabilities on demand.
Not an all-in-one bundle, but a progressively upgradeable Java AI SDK
AI4J's module split is not there to look "feature-rich". It exists so you can start from a very small entry point. You can pull in only ai4j for model calls and tool integration; if the project is already Spring Boot, switch to the starter's configuration style; if you later need state, workflow, team or repository tasks, move gradually into ai4j-agent, ai4j-coding and ai4j-cli.
The key to this path: each layer solves one problem on its own, and tries not to overturn the concepts of the layer below.
| Stage | Module to take | Main value |
|---|---|---|
| Get AI working first | ai4j | Plain Java projects can also call models, tools, RAG and MCP directly |
| Integrate into a Spring app | ai4j-spring-boot-starter | Manage model services through configuration and Beans, without locking business code into demo-style wiring |
| Build an Agent runtime | ai4j-agent | Adds memory, state, workflow, trace and team orchestration on top of the Core SDK |
| Tackle repository tasks | ai4j-coding + ai4j-cli | Productize the Agent capability into a local Coding Agent, CLI, TUI and session entry point |
| Build visual workflows | ai4j-flowgram-spring-boot-starter | Wire the Agent capability into the FlowGram backend and node execution system |
| Unify versions | ai4j-bom | Reduce version drift when combining multiple modules |
So AI4J's module independence is not "the directory is split finely", but rather "the user can take the piece they need at each stage".
Relationship with Spring AI, LangChain4j and AgentScope Java
Spring AI, LangChain4j and AgentScope Java all have larger teams, ecosystems and community momentum behind them. AI4J is not trying to out-scale them, and should not use "I beat them at everything" as a documentation selling point.
AI4J is better positioned to put the differences in these places:
| Dimension | AI4J's trade-off |
|---|---|
| Barrier to entry | Targets plain Java 8+ and Maven projects: get the call running first, then introduce advanced capability gradually |
| Conceptual boundaries | Explains Tool, Skill, MCP, RAG and Agent separately, to reduce the confusion of "everything is a chain" |
| Provider friendliness | Takes the real integration experience of OpenAI-compatible endpoints and domestic model platforms seriously |
| Module adoption | Does not force full adoption; Core SDK, starter, Agent, Coding, CLI and FlowGram can be introduced by stage |
| Upgrade path | Keeps one project mental model from Core SDK to Spring Boot starter, Agent, Coding Agent and FlowGram |
| Documentation strategy | No grand empty framework slogans; instead, writes down the entry point, suitable scenarios, limits and next step for each feature |
So AI4J's competitive point is not "bigger", but "easier to start inside a Java project, easier to explain clearly, easier to take on and upgrade as needed".
Core characteristics of AI4J
1. Plain Java can integrate first
You do not need to refactor the project into some complete application framework first, nor understand Agent, workflow or complex orchestration up front. Start from Quickstart for Java to verify the model configuration and a single call first.
If the project is already Spring Boot, go through Quickstart for Spring Boot and let the starter manage configuration and Beans.
2. Model capability is not an isolated wrapper
The Core SDK covers more than just chat():
- Chat
- Responses
- Streaming
- Multimodal
- Extension capabilities such as Embedding, Rerank, Image, Audio and Realtime
These capabilities should share configuration, provider integration and engineering constraints, instead of each one re-implementing a separate entry point.
3. Tool, Skill and MCP are layered clearly
AI4J does not collapse every external capability into a single concept:
- Tool: local function declaration, execution model and safety boundary.
- Skill: instructions, templates and task assets that the model can read.
- MCP: protocol-based integration of external tools and services.
This layering matters for both small and long-lived projects. Small projects avoid detours; long-lived projects keep boundaries from spiraling out of control during later refactors.
4. RAG and the retrieval chain can be introduced step by step
AI4J places Search & RAG on the main line of the Core SDK, rather than as a demo fully detached from model calls. You can use it progressively as needed:
- ingestion pipeline
- chunking
- embedding
- vector store
- hybrid retrieval
- rerank
- citations and trace
5. Upper-layer capability does not force itself on you from the start
Agent, Coding Agent and FlowGram are an upward upgrade path, not a prerequisite for first adopting AI4J.
When you need a more complex runtime, workflow, repository task or visual orchestration, then move into:
6. Multiple modules are a choice, not a burden
If you only need model calls, stop at ai4j. If you need Spring Boot auto-configuration, pull in the starter. If you are building an Agent runtime, Coding Agent or FlowGram, pick the corresponding module. AI4J should let you add capability gradually, not require you to accept a whole platform pipeline up front.
What projects it fits
AI4J is a better fit for:
- Projects already in the Java 8+ or Maven ecosystem that want to integrate AI quickly.
- Projects that want to stay compatible with both plain Java and Spring Boot.
- Projects that need OpenAI-compatible endpoints, domestic model platforms or multi-provider integration.
- Projects that may later upgrade from model calls to tools, RAG, MCP or Agent.
- Projects that want to take capability module by module, rather than pulling in a complete platform from the start.
- Teams that want documentation to explain features, boundaries and maturity clearly, not just hand over a demo.
AI4J is a worse fit for:
- The thinnest-wrapper scenario where you only want to bind one provider and need no extension capability at all.
- Projects already deeply bound to Spring AI, LangChain4j or another framework, where the current cost is low.
- Teams that need a large ecosystem, commercial support, a huge volume of third-party integrations or a long-term stable SLA.
- Projects that want all complexity hidden inside a black box, rather than accepting clear layering and explicit configuration.
What to read next
| What you want to do now | Next page |
|---|---|
| Get the first request working | Quickstart for Java |
| Plain Java first | Quickstart for Java |
| Spring Boot integration | Quickstart for Spring Boot |
| See the full feature map | Feature Map |
| Understand the Chat call | Model Access / Chat |
| Let the model call a local tool | First Tool Call |
If you are still unsure which line to take, start with Feature Map.