Embabel Agent Prerequisites: Complete Setup Guide for Java 17, Maven, and LLM Configuration

To run embabel-agent, you need Java 17 JDK, Maven 3+, Docker Desktop 4.43.2+, and an OpenAI API key.

Embabel Agent is a Spring Boot-based AI agent framework written in Kotlin that requires specific runtime and build dependencies. This guide covers every prerequisite found in the source code, from the java.version=17 declaration in pom.xml to the MCP tool requirements documented in the repository README.

Java Development Kit Requirements

The embabel-agent project enforces Java 17 as the minimum version across all modules.

In the root pom.xml, the Java version is explicitly set:

<properties>
    <java.version>17</java.version>
    <maven.compiler.source>${java.version}</maven.compiler.source>
    <maven.compiler.target>${java.version}</maven.compiler.target>
</properties>

The Maven Compiler Plugin (version 3.11.0) validates this at build time with the <release> flag, ensuring no backward compatibility issues occur.

To verify your installation:

java --version

# Expected output: openjdk 17.x.x or higher

javac --version

# Expected output: javac 17.x.x or higher

Build Tool Prerequisites

Embabel Agent supports both Maven and Gradle build systems. The repository provides pom.xml files throughout the project structure.

Maven Configuration

The embabel-agent-starter/pom.xml declares these key plugins:

• maven-compiler-plugin 3.11.0 for Java compilation
• kotlin-maven-plugin for Kotlin 2.0.21 source compilation
• spring-boot-maven-plugin for executable JAR creation

Kotlin Version Requirement

The project uses Kotlin 2.0.21 with KSP (Kotlin Symbol Processing) version 2.0.21-1.0.23. These versions must align exactly as specified in the properties block.

LLM Provider API Keys

Embabel Agent requires at least one LLM provider API key. The framework supports multiple backends through Spring AI integrations.

Required Environment Variables

Variable	Required For	Source
OPENAI_API_KEY	OpenAI GPT models (primary)	spring-ai-openai-spring-boot-starter
ANTHROPIC_API_KEY	Claude models (optional)	Additional provider configuration
MINIMAX_API_KEY	MiniMax Chinese LLMs (optional)	Extended provider support
ZAI_API_KEY	Z-AI models (optional)	Extended provider support

Set these before building or running:

export OPENAI_API_KEY=sk-your-key-here
export ANTHROPIC_API_KEY=sk-ant-your-key-here  # optional

Docker and MCP Tool Requirements

The embabel-agent framework integrates with Docker Desktop 4.43.2+ for containerized model execution and MCP (Model Context Protocol) tooling.

Required MCP Tools

The default configuration expects these MCP catalog tools to be available:

• Brave Search – web search capabilities
• Fetch – HTTP request execution
• Puppeteer – browser automation
• Wikipedia – knowledge base queries

These tools enable the agent to perform real-world actions beyond text generation.

Spring Boot and Spring AI Dependencies

The embabel-agent-starter/pom.xml declares core Spring dependencies:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>${spring.ai.version}</version>
</dependency>

The Spring AI version is currently pinned to 1.0.0-SNAPSHOT, which requires access to Spring milestone repositories.

Optional Local LLM Backends

For users preferring local inference, embabel-agent provides alternative starters:

Ollama Integration

Add the embabel-agent-starter-ollama dependency to connect to a local Ollama server:

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter-ollama</artifactId>
    <version>${embabel-agent.version}</version>
</dependency>

Docker Models

The embabel-agent-starter-dockermodels module enables Docker Desktop's built-in AI model runtime, eliminating external API key requirements for supported models.

Complete Setup Commands

Follow these steps to satisfy all embabel-agent prerequisites:

# 1. Verify Java 17

java --version

# 2. Verify Maven

mvn --version

# 3. Verify Docker Desktop

docker --version

# 4. Clone repository

git clone https://github.com/embabel/embabel-agent.git
cd embabel-agent

# 5. Configure environment

export OPENAI_API_KEY=sk-your-key-here

# 6. Build entire project

mvn clean install

# 7. Run shell starter for testing

cd embabel-agent-starters/embabel-agent-starter-shell
./mvnw spring-boot:run

Version-Specific Constraints

Component	Minimum Version	Configuration Location
Java	17	pom.xml <java.version>
Kotlin	2.0.21	pom.xml <kotlin.version>
Maven	3.8.x	Implicit from plugin versions
Docker Desktop	4.43.2	README documentation
Spring Boot	3.x	Parent POM inheritance
Spring AI	1.0.0-SNAPSHOT	pom.xml <spring.ai.version>

Summary

• Java 17 JDK is mandatory, enforced by Maven compiler configuration in pom.xml
• Maven 3+ is the primary build tool, with Kotlin compilation support via kotlin-maven-plugin
• OpenAI API key is required for default operation, with optional support for Anthropic, MiniMax, and Z-AI
• Docker Desktop 4.43.2+ enables MCP tool integration and local model execution
• Spring Boot and Spring AI provide the foundation for LLM integration and web capabilities
• Alternative starters exist for Ollama and Docker Models local inference

Frequently Asked Questions

Does embabel-agent work with Java 11 or 21?

No. The pom.xml explicitly sets java.version to 17, and the Maven compiler plugin enforces this with the <release>17</release> flag. While Java 21 may work, it is not tested or supported by the current build configuration.

Can I run embabel-agent without an OpenAI API key?

Only if you use an alternative LLM starter. The embabel-agent-starter-ollama or embabel-agent-starter-dockermodels modules enable local inference without external API keys. The default starter requires OPENAI_API_KEY due to its dependency on spring-ai-openai-spring-boot-starter.

Is Gradle officially supported?

The repository documentation references Gradle snippets, but all source configuration uses Maven pom.xml files. Gradle users must manually translate the dependency declarations from the published POM files.

What happens if Docker Desktop is not installed?

The framework will fail to initialize MCP tools that require containerized execution. Agents depending on web search, browser automation, or other MCP capabilities will encounter runtime errors. Core LLM functionality may still work if using direct API calls without tool integration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}