ai4j: a Java 8+ agentic SDK with unified LLM access, MCP and a built-in Coding Agent CLI

The Java 8 constraint ai4j is built around

Most agent frameworks in the Java ecosystem assume a recent JDK or a Spring Boot 3 baseline. ai4j takes the opposite position: the README describes it as a Java AI Agentic development kit for JDK 8+, and the badges repeat the JDK 8+ claim. That single constraint explains most of the project's shape. It is a multi-module Maven build, not a framework you plug into a container, and the core module sits alongside ai4j-agent, ai4j-cli, ai4j-coding, ai4j-spring-boot-starter, ai4j-flowgram-spring-boot-starter and a BOM. The intended reader is a backend engineer on an older runtime who needs tool calling, MCP or RAG and cannot move the JDK to get it. The README's own framing is that switching providers means replacing PlatformType and the matching Config while everything else stays the same.

One Configuration object, many platforms

The mechanism visible in the README is a service factory. You build a Configuration, attach a platform config object such as OpenAiConfig, hand it to AiService, and ask for a typed service with getChatService(PlatformType.OPENAI). The chat service is an interface, IChatService, and requests are built with a ChatCompletion builder that carries the model name and a message list. Responses come back as ChatCompletionResponse with a choices list, so the call is synchronous and blocking in the example. The same PlatformType enum is the switch for provider selection, which is why the README can claim that moving from OpenAI to DashScope, DeepSeek or Ollama only changes the enum value and the config object. Around that core the repository lists tool calling, MCP, A2A, RAG and an Agent Runtime, plus VectorStore integrations for Pinecone, Qdrant, pgvector, Milvus and Redis, and Rerank support for Jina, Ollama and Doubao. The design is deliberately thin at the call site and broad at the edges.

Installing ai4j and sending a first request

The README gives two install paths. Gradle users add a single implementation line, and Maven users add the same coordinate as a dependency. Version 2.4.2 is the one named in the README and matches the most recent release listed for the project.

# Gradle
implementation 'io.github.lnyo-cly:ai4j:2.4.2'

<!-- Maven -->
<dependency>
  <groupId>io.github.lnyo-cly</groupId>
  <artifactId>ai4j</artifactId>
  <version>2.4.2</version>
</dependency>

For the first call, the README's 30-second example sets the OPENAI_API_KEY environment variable and then runs a small main class. It constructs OpenAiConfig, sets the API key from the environment, wraps it in a Configuration, creates AiService, and requests the OPENAI chat service. The request uses the gpt-4o-mini model and a single user message. The response is printed by reading the first choice's message content.

OpenAiConfig openAiConfig = new OpenAiConfig();
openAiConfig.setApiKey(System.getenv("OPENAI_API_KEY"));
Configuration configuration = new Configuration();
configuration.setOpenAiConfig(openAiConfig);
AiService aiService = new AiService(configuration);
IChatService chatService = aiService.getChatService(PlatformType.OPENAI);
ChatCompletion request = ChatCompletion.builder()
        .model("gpt-4o-mini")
        .message(ChatMessage.withUser("用一句话介绍 ai4j"))
        .build();
ChatCompletionResponse response = chatService.chatCompletion(request);
System.out.println(response.getChoices().get(0).getMessage().getContent().getText());

What you should see is a single line of text printed to stdout. The README shows an example output describing ai4j as a JDK 8+ agentic kit covering unified model access, tool calling, MCP and RAG. Beyond this, the README points to a five-minute-first-chat document and a feature map in docs-site, and to a separate coding-agent-cli document for the CLI, TUI and ACP surface.

Where the abstraction leaks

The unified PlatformType story is the project's main selling point and also its main risk. Providers do not agree on parameters, streaming semantics or tool-call formats, and a single enum cannot hide that indefinitely. The README does not document how provider-specific options are passed when a field has no equivalent in the shared request object, and it does not describe a fallback path when a model name is valid for one platform and unknown to another. The first-call example is also blocking: chatCompletion returns a full response, and the README does not show a streaming variant at the call site. If your application needs token-by-token output for a chat UI, check the docs-site before committing. There is a second, quieter limitation. The project ships many modules, including a Coding Agent with CLI, TUI and ACP surfaces, but the README does not document rollback or upgrade procedures for those tooling components, and it does not describe what happens when an agent run fails midway.

How ai4j differs from Spring AI and LangChain4j

Spring AI and LangChain4j are the obvious comparisons, and the difference is not feature count. Spring AI assumes a Spring Boot baseline and leans on the framework's dependency injection and configuration model; ai4j offers a Spring Boot starter (ai4j-spring-boot-starter) but its core example is plain Java with an explicit Configuration object and a factory call, which is what makes JDK 8 support possible. LangChain4j centres on its own chain and memory abstractions, while ai4j exposes a service interface per capability and a PlatformType enum as the provider switch. The practical consequence: if your codebase is already Spring Boot 3, Spring AI fits the wiring you have, and ai4j's manual configuration is extra work. If your codebase is a Java 8 service with no DI container, ai4j's factory is closer to what you can actually call. The README also lists AgentFlow integrations for Dify, Coze and n8n, which suggests the project expects to sit beside external orchestration rather than replace it.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-09, which is recent enough that the project is being touched. The release history shows 2.4.0 and 2.4.1 on the same day in July 2026 and 2.4.2 two days later, a cadence that suggests rapid patch releases rather than long stabilisation windows. For adopters that means pinning the version matters: the README names 2.4.2, and the BOM module (ai4j-bom) exists precisely so multiple ai4j modules can share one version. The licence is Apache-2.0, which permits commercial use and modification and requires preservation of notices; this is a description of the licence text, not legal advice, and your own counsel should review obligations if you redistribute. The upgrade cost is mostly the PlatformType and Config surface: if a provider config class or the enum changes between minor versions, every call site that names it needs a recompile. The CHANGELOG and CONTRIBUTING files at the repository root are the places the project says to look for change history.

Editorial conclusion

Adopt ai4j when the constraint is a Java 8 runtime and you want one dependency covering chat, tool calling, MCP and RAG behind a single Configuration object; the Maven coordinate io.github.lnyo-cly:ai4j:2.4.2 is the entry point. Skip it if you already run Spring AI or LangChain4j and have no JDK 8 users, because you would be maintaining two abstraction layers for the same calls. Verify first that your target platform is in the supported list (OpenAI, Anthropic, DashScope, Doubao, DeepSeek, Moonshot, Zhipu, Hunyuan, Lingyi, Ollama, MiniMax, Baichuan, Suno) and that the module you need, ai4j-agent, ai4j-cli or ai4j-spring-boot-starter, is the one you actually plan to depend on.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. LnYo-Cly/ai4j on GitHub
3. Project website
4. README
5. Releases