Build and Test Embabel Agent: A Complete Maven Development Guide

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.

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 aggregates all modules and defines the build lifecycle. To compile, package, and validate the entire framework, use the verify goal:

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

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:

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:

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

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

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 hierarchy helps diagnose build issues and contributes effectively:

• pom.xml (root) — aggregates all modules, defines parent POM with dependency management, plugin versions, and build profiles. View source

• embabel-agent-api/pom.xml — core API module containing the framework's public interfaces. All starters declare this as a dependency. View source

• embabel-agent-test-support/embabel-agent-test/pom.xml — shared test utilities including mock configurations and test fixtures used across multiple modules. View source

• Starter modules (embabel-agent-openai, embabel-agent-anthropic, etc.) — provider-specific implementations with their own 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 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 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.

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