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

> Quickly set up your development environment for embabel-agent. Follow this guide to install dependencies, clone the repo, and verify your setup for seamless agent development.

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

---

**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](https://adoptium.net/) |
| **Maven 3.8+** | Build, dependency resolution, and test execution | [Maven](https://maven.apache.org/) |
| **Git** | Clone source repository | [Git](https://git-scm.com/) |
| **Docker Desktop ≥ 4.43.2** (optional) | Enables built-in MCP web tools (Brave Search, Fetch, Puppeteer, Wikipedia) | [Docker](https://www.docker.com/products/docker-desktop) |
| **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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) at lines 28-46:

```bash
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`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) (referencing lines 50-74 in the README):

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

```xml
<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)

```bash
mvn clean test

```

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

### Run Integration Tests

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

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

```java
@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`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) | Repository root | Parent descriptor with modules and dependency management |
| [`FakeOperationContext.java`](https://github.com/embabel/embabel-agent/blob/main/FakeOperationContext.java) | `embel-agent-test-support/.../test/` | Test utility capturing prompts and tool-group data |
| [`README.md`](https://github.com/embabel/embabel-agent/blob/main/README.md) | `embel-agent-api/` | Detailed API documentation, annotation syntax |
| [`README.md`](https://github.com/embabel/embabel-agent/blob/main/README.md) | `embel-agent-starters/embel-agent-starter/` | Starter integration guide |
| [`README.md`](https://github.com/embabel/embabel-agent/blob/main/README.md) | `embel-agent-shell/` | Shell commands and launch instructions |
| [`README.md`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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.