# Build and Test Embabel Agent: A Complete Maven Development Guide

> Learn how to build and test embabel-agent with simple Maven commands. This guide covers compiling modules, running unit tests, and executing integration tests effectively.

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

---

**You can build and test embabel-agent using standard Maven commands: `mvn clean verify` compiles all modules and runs unit tests, while `mvn -Dtest='*IT,!LLMOllama*IT' test` executes integration tests against real LLM providers.**

The embabel-agent framework is a multi-module **Maven** project that provides a unified API for building AI agents across different LLM providers. Whether you are contributing to the core library or developing against a specific starter module, the build process follows standard Maven conventions with clear separation between offline-safe unit tests and integration tests requiring API credentials.

This guide walks through the complete build and test workflow, from initial clone through CI-ready commands, based on the actual project structure in `embabel/embabel-agent`.

## Prerequisites and Environment Setup

Before building embabel-agent, ensure you have **JDK 17 or later** and **Maven 3.8+** installed. The project also supports the **Maven Wrapper** (`mvnw`) if you prefer not to install Maven system-wide.

### Required API Keys for Integration Tests

Integration tests call live LLM endpoints and require valid credentials. Set these environment variables before running integration tests:

| Variable | Provider | Required For |
|----------|----------|--------------|
| `OPENAI_API_KEY` | OpenAI | OpenAI starter tests |
| `ANTHROPIC_API_KEY` | Anthropic | Anthropic starter tests |

Optional variables and detailed configuration are documented in the README's [environment variables section](https://github.com/embabel/embabel-agent/blob/main/README.md#environment-variables).

```bash
export OPENAI_API_KEY=sk-your-key-here
export ANTHROPIC_API_KEY=sk-ant-your-key-here

```

## Building the Complete Project

The root [`pom.xml`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) aggregates all modules and defines the build lifecycle. To compile, package, and validate the entire framework, use the **verify** goal:

```bash

# Clone and enter the repository

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

# Full build with unit tests

mvn clean verify

```

The `verify` phase executes:
- Compilation of all Java and Kotlin sources
- Packaging of each module into JAR artifacts
- Execution of **unit tests** (mock-based, no external services)

This command is **safe to run offline** and serves as the primary CI validation step.

## Running Tests: Unit vs. Integration

The project maintains a strict separation between test types, controlled through Maven profiles and naming conventions.

### Unit Tests (Offline Safe)

Unit tests use mocked LLM interactions and execute quickly without network dependencies. Run them with:

```bash
mvn test

```

These tests validate core logic in modules like `embabel-agent-api` and shared utilities in `embabel-agent-test-support/embabel-agent-test`.

### Integration Tests (Requires API Keys)

Integration tests follow the `*IT` naming pattern and exercise real provider endpoints. The recommended command selectively runs these while excluding Ollama-specific tests that require a local server:

```bash
mvn -Dtest='*IT,!LLMOllama*IT' -Dsurefire.failIfNoSpecifiedTests=false test

```

- `*IT` — includes all integration test classes
- `!LLMOllama*IT` — excludes Ollama tests (require local `ollama` installation)
- `-Dsurefire.failIfNoSpecifiedTests=false` — prevents failure when filtering excludes all tests in a module

## Building Specific Modules

For focused development on a single starter, use the `-pl` (projects list) flag to limit scope. This significantly reduces build time:

```bash

# Build and test only the OpenAI starter

mvn -Dtest='*IT' -pl embabel-agent-openai test

```

You can also combine module selection with test skipping for rapid iteration:

```bash

# Compile OpenAI starter without tests

mvn clean install -DskipTests -pl embabel-agent-openai

```

## Quick Compilation Without Tests

For scenarios where you need compiled artifacts but can defer validation—such as populating a local Maven repository for dependent projects—skip the test phase entirely:

```bash
mvn clean install -DskipTests

```

This produces installable JARs in your local `~/.m2/repository` for other projects to consume.

## Key Build Files and Module Structure

Understanding the [`pom.xml`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) hierarchy helps diagnose build issues and contributes effectively:

- **[`pom.xml`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) (root)** — aggregates all modules, defines parent POM with dependency management, plugin versions, and build profiles. [View source](https://github.com/embabel/embabel-agent/blob/main/pom.xml)

- **[`embabel-agent-api/pom.xml`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/pom.xml)** — core API module containing the framework's public interfaces. All starters declare this as a dependency. [View source](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/pom.xml)

- **[`embabel-agent-test-support/embabel-agent-test/pom.xml`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-test-support/embabel-agent-test/pom.xml)** — shared test utilities including mock configurations and test fixtures used across multiple modules. [View source](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-test-support/embabel-agent-test/pom.xml)

- **Starter modules** (`embabel-agent-openai`, `embabel-agent-anthropic`, etc.) — provider-specific implementations with their own [`pom.xml`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) files extending the parent configuration.

## Summary

- **`mvn clean verify`** — standard full build with unit tests, suitable for CI and offline development
- **`mvn test`** — run only unit tests (mock-based, fast, no API keys needed)
- **`mvn -Dtest='*IT,!LLMOllama*IT' test`** — run integration tests against live providers (requires `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`)
- **`-pl <module>`** — restrict build to specific starter for faster iteration
- **`-DskipTests`** — bypass all tests for quick compilation
- The **Maven Wrapper** (`mvnw`) provides version-consistent builds without system Maven installation

## Frequently Asked Questions

### How do I build embabel-agent without running any tests?

Use `mvn clean install -DskipTests`. This compiles all modules and installs JARs to your local Maven repository without executing the test suite. Ideal for setting up dependent projects or CI caching stages.

### Which tests require API keys, and which do not?

**Unit tests** (`mvn test`) require no API keys—they use mocked LLM responses and run entirely offline. **Integration tests** (`*IT` classes) require valid `OPENAI_API_KEY` and/or `ANTHROPIC_API_KEY` environment variables to call live endpoints. The Ollama integration tests additionally require a local Ollama server and are excluded by default.

### Can I build just one starter module instead of everything?

Yes. Use the `-pl` flag with the module's directory name, such as `mvn clean verify -pl embabel-agent-openai`. The module's [`pom.xml`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) will still resolve dependencies from other modules in the reactor, but compilation and testing are limited to the specified project.

### Where are the test commands officially documented?

The [README.md Testing section](https://github.com/embabel/embabel-agent/blob/main/README.md#running-tests) provides the canonical commands and environment variable requirements. This guide consolidates and expands those instructions with additional context on module-specific builds and CI optimization.