# How to Install Embabel Agent: A Complete Setup Guide for JVM-Based LLM Applications

> Install Embabel Agent for your JVM LLM apps. Follow this guide to add the embabel-agent-starter dependency, configure repositories, and set API keys via environment variables.

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

---

**Add the `embabel-agent-starter` dependency to your Maven or Gradle build, configure the required repositories (only for versions < 0.2.0), and set your LLM provider API keys as environment variables.**

Embabel Agent is a JVM-based framework for building LLM-driven, agentic applications using Kotlin 1.9. This guide walks through the complete embabel-agent installation process for both Maven and Gradle projects, including optional starters for local models and observability.

## Prerequisites for Installing Embabel Agent

Before adding the embabel-agent dependency, ensure your environment meets these requirements:

- **Java 17 or higher** — the framework runs on any recent JDK, though built with Kotlin 1.9
- **Maven 3.x** or **Gradle** — standard build tools used throughout the embabel-agent source
- **LLM provider API key** — OpenAI, Anthropic, MiniMax, Z.ai, or Google Studio depending on your target models

Unit tests require no external services and can verify your installation immediately after setup.

## Installing Embabel Agent with Maven

### Maven Central (Recommended for v0.2.0+)

For versions 0.2.0 and later, the embabel-agent-starter artifact is published on Maven Central. No additional repository configuration is needed per the README's *Maven* section.

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

```

Replace `${embabel-agent.version}` with the current stable version (e.g., `0.3.0`).

### Pre-0.2.0 Releases and Snapshot Builds

For older versions or snapshot releases, add the Embabel repositories before your dependencies as documented in *Maven Central Availability*:

```xml
<repositories>
    <repository>
        <id>embabel-releases</id>
        <url>https://repo.embabel.com/artifactory/libs-release</url>
        <releases><enabled>true</enabled></releases>
        <snapshots><enabled>false</enabled></snapshots>
    </repository>
    <repository>
        <id>embabel-snapshots</id>
        <url>https://repo.embabel.com/artifactory/libs-snapshot</url>
        <releases><enabled>false</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
    </repository>
</repositories>

```

Then include the same dependency block as above.

## Installing Embabel Agent with Gradle

### Kotlin DSL

The embabel-agent README provides this Kotlin DSL configuration from the *Gradle (Kotlin DSL)* section:

```kotlin
repositories {
    mavenCentral()
    maven {
        name = "Spring Milestones"
        url = uri("https://repo.spring.io/milestone")
    }
}
dependencies {
    implementation("com.embabel.agent:embabel-agent-starter:${embabelAgentVersion}")
}

```

### Groovy DSL

For Groovy-based builds, use this syntax from *Gradle (Groovy DSL)*:

```groovy
repositories {
    mavenCentral()
    maven {
        name = 'Spring Milestones'
        url = 'https://repo.spring.io/milestone'
    }
}
dependencies {
    implementation "com.embabel.agent:embabel-agent-starter:${embelAgentVersion}"
}

```

## Optional Embabel Agent Starter Modules

The embabel-agent framework provides specialized starters for specific LLM providers and observability. These are documented in the *Observability* and *Local models* sections of the README.

| Module | Purpose | Artifact ID |
|--------|---------|-------------|
| `embabel-agent-starter-ollama` | Local Ollama server integration | `embel-agent-starter-ollama` |
| `embel-agent-starter-dockermodels` | Docker-hosted LLM containers | `embel-agent-starter-dockermodels` |
| `embel-agent-starter-observability` | OpenTelemetry tracing with Zipkin or Langfuse | `embel-agent-starter-observability` |

Add any of these alongside the core starter:

```kotlin
// Gradle Kotlin DSL with observability
dependencies {
    implementation("com.embel.agent:embel-agent-starter:0.3.0")
    implementation("com.embel.agent:embel-agent-starter-observability:0.3.0")
}

```

The module descriptors are located at:
- [`embel-agent-starter/pom.xml`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-starter/pom.xml) — core starter transitive dependencies
- [`embel-agent-starter-observability/pom.xml`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-starter-observability/pom.xml) — OpenTelemetry and exporter configuration
- [`embel-agent-starter-ollama/pom.xml`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-starter-ollama/pom.xml) — Ollama client integration
- [`embel-agent-starter-dockermodels/pom.xml`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-starter-dockermodels/pom.xml) — Docker model runtime support

## Required Environment Variables for Embabel Agent

After installing embabel-agent, configure these environment variables as specified in the *Environment variables* section:

| Variable | Required For |
|----------|--------------|
| `OPENAI_API_KEY` | OpenAI models |
| `ANTHROPIC_API_KEY` | Anthropic Claude models |
| `MINIMAX_API_KEY` | MiniMax models |
| `ZAI_API_KEY` | Z.ai models |
| `GOOGLE_STUDIO_API_KEY` | Gemini (A2A) integration |

Set these in your shell, IDE run configuration, or a `.env` file before application startup.

## Verifying Your Embabel Agent Installation

Run the unit test suite to confirm proper installation without external dependencies:

```bash
mvn test

```

Integration tests require configured API keys and network access to LLM providers.

Alternatively, clone the repository and run the starter shell (requires Docker Desktop with MCP tools):

```bash
git clone https://github.com/embel/embel-agent
cd embel-agent
./mvnw spring-boot:run

```

## Summary

- **Java 17+ and Maven 3.x/Gradle** are required to install embel-agent
- **Maven Central** hosts v0.2.0+ with no extra repositories; older versions need `repo.embel.com`
- **`embel-agent-starter`** is the core dependency; optional starters add Ollama, Docker models, or observability
- **API keys** must be set as environment variables before runtime
- **Unit tests** (`mvn test`) verify installation without external services

## Frequently Asked Questions

### What Java version does Embel Agent require?

Embel Agent requires **Java 17 or higher**. The framework is built with Kotlin 1.9 but runs on any recent JDK. This is verified across all starter modules in the repository.

### Do I need special repositories to install Embel Agent?

**Only for versions before 0.2.0.** Current releases (0.2.0+) are on Maven Central. For snapshots or legacy versions, add the Embel Artifactory repositories as shown in the README's *Maven Central Availability* section.

### Can I run Embel Agent with local LLMs instead of cloud APIs?

Yes. Install the **`embel-agent-starter-ollama`** module for Ollama integration, or **`embel-agent-starter-dockermodels`** for Docker-hosted models. These starters eliminate the need for cloud API keys when using local inference.

### How do I add tracing and monitoring to my Embel Agent application?

Include the **`embel-agent-starter-observability`** dependency. This starter auto-configures OpenTelemetry with support for Zipkin, Langfuse, and other telemetry backends per the *Observability* section of the README.