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

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
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
embabel-agent-code	Compile-time code generation and Maven tooling	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
embabel-agent-a2a	A2A protocol integration with streaming handler	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

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:

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:

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

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

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:

@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 – high-level overview, quick-start, and contribution guidelines
• pom.xml (root) – module aggregation and BOM definitions
• 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 – A2A streaming implementation
• 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), 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 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.

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