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

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.

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

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

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):

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:

// 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 — core starter transitive dependencies
• embel-agent-starter-observability/pom.xml — OpenTelemetry and exporter configuration
• embel-agent-starter-ollama/pom.xml — Ollama client integration
• 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:

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):

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.

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