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

> Learn the essential embabel agent prerequisites including Java 17 JDK Maven Docker Desktop and OpenAI API key configuration. Get your agent running smoothly with this setup guide.

- Repository: [Embabel/embabel-agent](https://github.com/embabel/embabel-agent)
- Tags: getting-started
- Published: 2026-08-14

---

**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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/pom.xml), the Java version is explicitly set:

```xml
<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:

```bash
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`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) files throughout the project structure.

### Maven Configuration

The [`embabel-agent-starter/pom.xml`](https://github.com/embabel/embabel-agent/blob/main/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:

```bash
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`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-starter/pom.xml) declares core Spring dependencies:

```xml
<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:

```xml
<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:

```bash

# 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`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) `<java.version>` |
| Kotlin | 2.0.21 | [`pom.xml`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) `<spring.ai.version>` |

## Summary

- **Java 17 JDK** is mandatory, enforced by Maven compiler configuration in [`pom.xml`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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.