How to Set Up a Development Environment for embabel-agent: A Complete Setup Guide

Install Java 17+, Maven 3.8+, and Git, clone the embabel-agent repository, and run mvn clean test to verify your setup; the framework requires OPENAI_API_KEY even for offline unit tests.

The embabel-agent framework from Embabel provides a modular, Spring-based platform for building agentic flows on the JVM. This guide walks through setting up a complete development environment for embabel-agent, covering prerequisites, repository structure, build verification, and essential tooling based on the actual source code in the embabel/embabel-agent repository.

Prerequisites for embabel-agent Development

Before cloning the repository, ensure your machine meets these requirements:

Requirement	Purpose	Installation
Java 17+	Core runtime for all JVM modules	Adoptium
Maven 3.8+	Build, dependency resolution, and test execution	Maven
Git	Clone source repository	Git
Docker Desktop ≥ 4.43.2 (optional)	Enables built-in MCP web tools (Brave Search, Fetch, Puppeteer, Wikipedia)	Docker
OpenAI/Anthropic API keys	Required for integration tests and demo agents	Provider dashboards

Critical: Set OPENAI_API_KEY in your environment—even a dummy value works—because the test harness in pom.xml and test utilities expect this variable.

Clone the embabel-agent Repository

The embabel-agent project uses a multi-module Maven structure defined in the parent pom.xml at lines 28-46:

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

Module Structure

Module	Location	Purpose
embabel-agent-api	/embabel-agent-api	Core annotation-driven DSL, agent plumbing
embabel-agent-starters	/embabel-agent-starters	Spring Boot starters (default, Ollama, OCI-GenAI)
embabel-agent-rag	/embabel-agent-rag	Retrieval-augmented generation utilities
embabel-agent-shell	/embabel-agent-shell	Interactive Spring Shell for prototyping
embabel-agent-observability	/embabel-agent-observability	Auto-instrumentation for tracing/metrics

Configure Maven Repositories

Release Versions (≥ 0.2.0)

For embabel-agent version 0.2.0 or later, artifacts are available on Maven Central—no additional repository configuration needed.

Snapshot Versions

For older snapshots or bleeding-edge builds, add Embabel repositories to your pom.xml (referencing lines 50-74 in the README):

<repositories>
    <repository>
        <id>embabel-releases</id>
        <url>https://repo.embabel.com/artifactory/libs-release</url>
    </repository>
    <repository>
        <id>embabel-snapshots</id>
        <url>https://repo.embel.com/artifactory/libs-snapshot</url>
    </repository>
</repositories>

Add the Starter Dependency

The fastest path to building with embabel-agent is the Spring Boot starter in embel-agent-starters/embel-agent-starter:

<dependency>
    <groupId>com.embel.agent</groupId>
    <artifactId>embel-agent-starter</artifactId>
    <version>${embel-agent.version}</version>
</dependency>

The starter transitively pulls in:

• Core API from embel-agent-api
• Default GOAP planner implementation
• Spring AI integration layer

Build and Verify Your embabel-agent Environment

Run Unit Tests (Offline)

mvn clean test

This executes tests using FakeOperationContext and other test utilities in embel-agent-test-support that mock LLM interactions.

Run Integration Tests

mvn -Dtest='*IT,!LLMOllama*IT' test

Excludes Ollama-specific tests while running remaining integration tests against live LLM providers.

Launch the Interactive Shell

The embel-agent-shell module provides a REPL for rapid prototyping without writing main() classes:

cd embel-agent-shell
mvn spring-boot:run

Example Shell Command

execute "Lynda is a Scorpio, find news for her" -p -r

• -p: Logs the LLM prompt
• -r: Logs the LLM response

Recommended Development Workflow

1. Bootstrap with Templates

   Use official GitHub templates to start fresh projects:

   • Java: embel/java-agent-template
   • Kotlin: embel/kotlin-agent-template

2. Test-Driven Development

   Follow the repository philosophy: write tests asserting generated prompts contain expected data, then implement actions. Reference StarNewsFinderTest in the README example section.

3. Enable Observability

   Add embel-agent-starter-observability dependency plus a tracing exporter (Zipkin or Langfuse) to visualize execution flows. Mark custom spans with @Tracked.

4. Leverage Docker MCP Tools

   With Docker Desktop running, enable the MCP catalog for web-search tools—simplifies research-heavy agents requiring Brave Search, Fetch, or Puppeteer.

Minimal Agent Example

This agent from the README's "Show Me The Code" section demonstrates core annotations:

@Agent(description = "Find news based on a person's star sign")
public class StarNewsFinder {

    private final HoroscopeService horoscopeService;
    private final int storyCount;

    public StarNewsFinder(HoroscopeService horoscopeService,
                          @Value("${star-news-finder.story.count:5}") int storyCount) {
        this.horoscopeService = horoscopeService;
        this.storyCount = storyCount;
    }

    @Action
    public StarPerson extractStarPerson(UserInput userInput, Ai ai) {
        return ai.withLlm(OpenAiModels.GPT_4)
                 .createObjectIfPossible(
                     "Create a person from this user input, extracting name and star sign: %s"
                         .formatted(userInput.getContent()),
                     StarPerson.class);
    }

    @Action
    public Horoscope retrieveHoroscope(StarPerson starPerson) {
        return new Horoscope(horoscopeService.dailyHoroscope(starPerson.sign()));
    }

    @Action(toolGroups = {CoreToolGroups.WEB})
    public Writeup writeup(StarPerson person, Horoscope horoscope, Ai ai) {
        var prompt = """
            Write a short, amusing write-up for %s (%s) using the horoscope:
            %s
            """.formatted(person.name(), person.sign(), horoscope.summary());

        return ai.withLlm(LlmOptions.withModel(OpenAiModels.GPT_4_MINI).withTemperature(0.9))
                 .createObject(prompt, Writeup.class);
    }
}

Key patterns: @Agent marks the class, @Action denotes plannable operations, toolGroups enables web tools, and Ai parameter provides fluent LLM access.

Key Source Files in embabel-agent

File	Path	Description
pom.xml	Repository root	Parent descriptor with modules and dependency management
FakeOperationContext.java	embel-agent-test-support/.../test/	Test utility capturing prompts and tool-group data
README.md	embel-agent-api/	Detailed API documentation, annotation syntax
README.md	embel-agent-starters/embel-agent-starter/	Starter integration guide
README.md	embel-agent-shell/	Shell commands and launch instructions
README.md	embel-agent-observability/	Tracing setup with Zipkin/Langfuse

Summary

Setting up an embabel-agent development environment requires:

• Java 17+ and Maven 3.8+ as non-negotiable base tooling
• Environment variables (OPENAI_API_KEY minimum) for test compatibility
• Multi-module Maven build verified via mvn clean test
• Spring Boot starter as the recommended integration path
• Optional Docker Desktop for MCP web tools and enhanced agent capabilities
• Interactive shell in embel-agent-shell for rapid experimentation

Frequently Asked Questions

What Java version does embabel-agent require?

The framework requires Java 17 or higher, matching the version specified in the parent pom.xml. The project compiles with newer LTS versions (21+) but maintains 17 as the baseline compatibility target.

Why does mvn test fail without an API key?

The test harness expects OPENAI_API_KEY to be present in the environment—even a dummy value like sk-test satisfies this requirement. The FakeOperationContext utility in embel-agent-test-support uses this variable during initialization, though actual HTTP calls are mocked in unit tests.

Can I develop embel-agent without Docker?

Yes. Docker Desktop ≥ 4.43.2 is only required for the MCP tool suite (Brave Search, Fetch, Puppeteer, Wikipedia). Core agent development, unit testing, and integration testing against cloud LLM providers work without any container runtime.

How do I debug an agent's planning decisions?

Add the embel-agent-starter-observability dependency and configure a tracing exporter. The framework auto-instruments agent execution flows, and you can add custom @Tracked annotations to methods for granular visibility into planner activity and action selection.

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