# How to Contribute to Embabel-Agent: A Complete Guide to the Spring-Based Agentic Framework

> Contribute to the Embabel-Agent Spring framework by forking the repo, setting up Java 17+, running tests, and submitting Kotlin-first pull requests. Learn how to join the development team.

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

---

**To contribute to embabel-agent, fork the repository, set up Java 17+ and Maven, run the test suite, and submit pull requests following the project's Kotlin-first coding style and 100% test coverage requirements.**

The **embabel-agent** project is a modular, Spring-based framework for building **agentic flows** on the JVM. If you want to contribute to embabel-agent, understanding its GOAP/Utility-AI architecture and module organization is essential. This guide walks you through the contribution process using the actual source structure from the `embabel/embabel-agent` repository.

## Understanding the Embabel-Agent Architecture

Before you contribute to embabel-agent, familiarize yourself with its multi-module Maven structure. Each module serves a distinct purpose:

| Module | Responsibility | Key Source Location |
|--------|--------------|---------------------|
| **embabel-agent-api** | Core SPI with annotations (`@Agent`, `@Action`, `@Goal`), message-prompt builders, utility planners | [`embabel-agent-api/src/main/kotlin/com/embabel/agent/spi/support/messagePromptBuilders.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/src/main/kotlin/com/embabel/agent/spi/support/messagePromptBuilders.kt) |
| **embabel-agent-common** | Shared runtime utilities including Web MVC and SSE controller | [`embabel-agent-common/embabel-agent-webmvc/src/main/kotlin/com/embabel/agent/web/sse/SseController.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-common/embabel-agent-webmvc/src/main/kotlin/com/embabel/agent/web/sse/SseController.kt) |
| **embabel-agent-code** | Compile-time code generation and Maven tooling | [`embabel-agent-code/src/test/kotlin/com/embabel/coding/tools/jvm/MavenBuildSystemIntegrationTest.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-code/src/test/kotlin/com/embabel/coding/tools/jvm/MavenBuildSystemIntegrationTest.kt) |
| **embabel-agent-anthropic** | Anthropic LLM bindings and caching configuration | [`embabel-agent-anthropic/src/main/kotlin/com/embabel/agent/anthropic/AnthropicModelFactory.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-anthropic/src/main/kotlin/com/embabel/agent/anthropic/AnthropicModelFactory.kt) |
| **embabel-agent-a2a** | A2A protocol integration with streaming handler | [`embabel-agent-a2a/src/main/kotlin/com/embabel/agent/a2a/server/support/A2AStreamingHandler.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-a2a/src/main/kotlin/com/embabel/agent/a2a/server/support/A2AStreamingHandler.kt) |
| **embabel-agent-starter-*** | Spring Boot starters for Ollama, OCI, and Observability runtimes | [`embel-agent-starter-ollama/pom.xml`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-starter-ollama/pom.xml) |

The framework implements a **GOAP/Utility-AI planning core**. Agents are Spring beans annotated with `@Agent`. Their behavior is expressed as **actions** (`@Action`) that manipulate domain objects. The planner dynamically builds plans—sequences of actions—to achieve declared **goals** (`@Goal`). Conditions re-evaluate after each action, enabling dynamic replanning.

## Step-by-Step: How to Contribute to Embabel-Agent

### 1. Fork and Clone the Repository

Start by forking `embabel/embabel-agent` on GitHub, then clone your fork locally:

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

```

### 2. Set Up Your Development Environment

Contributing to embabel-agent requires:

- **Java 17+**
- **Maven**
- **Docker Desktop** (optional, for MCP tools)

The README's *Quick Start* section provides detailed setup instructions.

### 3. Run the Test Suite

Validate your environment before making changes:

```bash
mvn test

```

Unit tests run offline. Integration tests requiring API keys are excluded by default. Check the *Running Tests* section in the README for configuration details.

### 4. Find or Propose Work

Browse the repository's issue tracker for open bugs, feature requests, and `help-wanted` tags. You can also propose new features by opening an issue for discussion.

### 5. Create a Feature Branch

```bash
git checkout -b my-feature

```

Use descriptive branch names that indicate the change scope.

### 6. Follow the Coding Style

When you contribute to embabel-agent, adhere to these language preferences:

- **Kotlin** for new code
- **Java** for modifications to existing Java files

The complete style guide lives at [`embel-agent-api/.embel/coding-style.md`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-api/.embel/coding-style.md) in the repository.

### 7. Write Tests First

The CI pipeline enforces **100% test coverage** for new functionality. Use:

- **MockK** for Kotlin unit tests
- **Mockito** for Java unit tests

### 8. Update Documentation

If your contribution introduces new public APIs, add or adjust Asciidoctor snippets in `embel-agent-docs`. The documentation source is at `embel-agent-docs/README.adoc`.

### 9. Commit Your Changes

```bash
git commit -m "Brief, descriptive commit message"

```

Never push directly to the upstream `main` branch.

### 10. Open a Pull Request

Submit your PR against the upstream `main` branch. The CI automatically runs:

- Maven builds
- Unit tests
- SonarCloud analysis

### 11. Address Review Feedback

Respond to maintainer comments promptly. Once all checks pass and reviewers approve, a maintainer will merge your contribution.

## Code Example: Minimal Agent Implementation

Here's a complete Java agent from the embabel-agent source, demonstrating the core annotations:

```java
@Agent(description = "Echoes the input string")
public class EchoAgent {

    @Action
    public String echo(String input) {
        return input;
    }

    @AchievesGoal(
        description = "Return the echoed message",
        export = @Export(
            remote = true,
            name = "echoService",
            startingInputTypes = {String.class}
        )
    )
    @Action
    public String run(String input) {
        return echo(input);
    }
}

```

This example originates from the README's "Show Me The Code" section. Key elements include:

- **`@Agent`** – marks the class as an agent component
- **`@Action`** – defines executable behavior units
- **`@AchievesGoal`** – declares which goal this action satisfies, with export configuration for remote exposure

## Essential Files for Contributors

When you contribute to embabel-agent, bookmark these locations:

- **[`README.md`](https://github.com/embabel/embabel-agent/blob/main/README.md)** – high-level overview, quick-start, and contribution guidelines
- **[`pom.xml`](https://github.com/embabel/embabel-agent/blob/main/pom.xml)** (root) – module aggregation and BOM definitions
- **[`embel-agent-api/src/main/kotlin/com/embel/agent/spi/support/messagePromptBuilders.kt`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-api/src/main/kotlin/com/embel/agent/spi/support/messagePromptBuilders.kt)** – core prompt-building utilities
- **[`embel-agent-a2a/src/main/kotlin/com/embel/agent/a2a/server/support/A2AStreamingHandler.kt`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-a2a/src/main/kotlin/com/embel/agent/a2a/server/support/A2AStreamingHandler.kt)** – A2A streaming implementation
- **[`embel-agent-starter-ollama/pom.xml`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-starter-ollama/pom.xml)** – reference starter for local model deployment
- **`embel-agent-docs/README.adoc`** – public documentation source

## Summary

To successfully contribute to embabel-agent:

- Understand the **GOAP/Utility-AI** architecture and **multi-module Maven** structure
- Use **Kotlin for new code**, Java for existing files
- Maintain **100% test coverage** with MockK or Mockito
- Update **Asciidoctor documentation** for API changes
- Submit PRs against `main` and address **CI and reviewer feedback**

## Frequently Asked Questions

### What programming languages does embabel-agent use?

The embabel-agent framework uses **Kotlin as the preferred language for new code** and **Java for existing files**. The core API is implemented in Kotlin ([`messagePromptBuilders.kt`](https://github.com/embabel/embabel-agent/blob/main/messagePromptBuilders.kt)), while many examples and integrations support both languages.

### Do I need API keys to run embabel-agent tests?

No. **Unit tests run offline** without API keys. Integration tests requiring external API keys are **excluded by default**. Configure your environment only if you need to run the full integration test suite.

### What is the A2A protocol in embabel-agent?

The **A2A (Agent-to-Agent) protocol** enables inter-agent communication. In embabel-agent, this is implemented in the `embel-agent-a2a` module, with streaming support via [`A2AStreamingHandler.kt`](https://github.com/embabel/embabel-agent/blob/main/A2AStreamingHandler.kt) for real-time agent interactions.

### How does the embabel-agent planner work?

The embabel-agent planner implements **GOAP (Goal-Oriented Action Planning)** combined with **Utility-AI**. It dynamically constructs action sequences to achieve `@Goal` annotations, re-evaluating world state conditions after each action to enable adaptive replanning.