# What Is the Core Purpose of the embabel-agent Repository?

> Discover the core purpose of the embabel-agent repository: a JVM framework for authoring agentic flows that integrate LLM prompts with code and domain models.

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

---

**The embabel-agent repository is a framework for authoring agentic flows on the JVM that seamlessly combine large-language-model (LLM) prompts with ordinary code and domain models.**

Built on Spring Boot, embabel-agent enables developers to build type-safe, observable AI agents that can plan, replan, and interact with external tools while maintaining full testability.

## Three Fundamental Concepts

At the heart of embabel-agent are three annotated constructs that define agent behavior:

- **Agent** — A Spring-managed component annotated with `@Agent` that groups Actions, Goals, and Conditions to achieve a purpose.
- **Action** — A single step marked with `@Action`; can be pure Java/Kotlin code, an LLM-driven prompt, or a tool-enabled operation.
- **Goal** — The target state the agent strives toward, with dynamic planning performed via GOAP or Utility AI.

**Conditions** serve as preconditions and post-conditions evaluated after each action to determine whether execution continues or triggers replanning.

These concepts work together within the **AgentPlatform**, the runtime interface defined in [`embabel-agent-api/src/main/kotlin/com/embabel/agent/core/AgentPlatform.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/src/main/kotlin/com/embabel/agent/core/AgentPlatform.kt) that orchestrates execution modes, replanning, tool integration, and observability.

## Dynamic Planning Architecture

The embabel-agent framework offers pluggable planning strategies:

- **Goal-Oriented Action Planning (GOAP)** — The default planner using a proven AI planning algorithm.
- **Utility AI** — An alternative mode that selects actions based on utility scores for open-ended exploration.

Planning is implemented as a plugin interface in [`embabel-agent-api/src/main/kotlin/com/embabel/agent/core/support/DefaultAgentPlatform.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/src/main/kotlin/com/embabel/agent/core/support/DefaultAgentPlatform.kt), allowing custom planners to be swapped in as needed.

## Strongly-Typed Domain Model

Domain objects in embabel-agent are regular POJOs or Kotlin data classes with Jackson metadata. This gives LLMs a clear schema to work against while guaranteeing compile-time safety when Actions accept or produce these objects.

## Seamless LLM and Tool Integration

Actions can invoke LLMs via `ai.withLlm(...)` and request external tools through the **Model-Context-Protocol (MCP)**. Tool groups are declaratively provisioned:

```java
@Action(toolGroups = {CoreToolGroups.WEB})

```

This automatically provisions capabilities like web search.

## Execution Modes

The `AgentPlatform` supports three execution modes as implemented in the core runtime:

| Mode | Behavior |
|------|----------|
| **Focused** | Direct method call to a specific agent |
| **Closed** | Request-driven agent selection from registered agents |
| **Open** | Platform discovers a goal and composes a custom agent dynamically |

## Code Example: Minimal Java Agent

```java
@Agent(description = "Echoes the user's message")
public class EchoAgent {

    @Action
    public String echo(String input) {
        return input;                 // simple pure‑code action
    }

    @AchievesGoal(description = "Return the echoed text")
    @Action
    public String echoWithLlm(String input, Ai ai) {
        return ai.withDefaultLlm()
                .createObject(
                    "Return the following text verbatim:\n%s".formatted(input),
                    String.class);
    }
}

```

## Code Example: Kotlin Agent with Web Tools

```kotlin
@Agent(description = "Find news for a zodiac sign")
class StarNewsAgent(
    private val horoscopeService: HoroscopeService,
    @param:Value("\${story.count:5}") private val storyCount: Int = 5
) {

    @Action
    fun extractPerson(userInput: UserInput, ai: Ai): StarPerson =
        ai.withDefaultLlm()
          .createObject("Create a person from this input: $userInput")

    @Action
    fun retrieveHoroscope(star: StarPerson) =
        Horoscope(horoscopeService.dailyHoroscope(star.sign))

    @Action(toolGroups = [ToolGroup.WEB])
    fun findNews(star: StarPerson, horoscope: Horoscope, ai: Ai): RelevantNewsStories =
        ai.withDefaultLlm().createObject(
            """
            ${star.name} is a ${star.sign}. Their horoscope: ${horoscope.summary}
            Use web tools to find $storyCount relevant news stories and summarize them.
            """.trimIndent()
        )
}

```

## Observability and Testability

The framework delivers production-ready observability through:

- Built-in tracing via **Zipkin** and **Langfuse**, automatically recording agent lifecycle, action spans, LLM usage, and tool calls via `AgentPlatformEvent` in [`embabel-agent-api/src/main/kotlin/com/embabel/agent/api/event/AgentPlatformEvent.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/src/main/kotlin/com/embabel/agent/api/event/AgentPlatformEvent.kt)
- Unit-test helpers including `FakeOperationContext` and `AgentPlatformTestExtensions` for straightforward prompt verification

## Key Source Files

Understanding the embabel-agent architecture requires examining these files:

- [`embabel-agent-api/src/main/kotlin/com/embabel/agent/core/AgentPlatform.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/src/main/kotlin/com/embabel/agent/core/AgentPlatform.kt) — Core runtime interface for execution modes and replanning
- [`embabel-agent-api/src/main/kotlin/com/embabel/agent/core/support/DefaultAgentPlatform.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/src/main/kotlin/com/embabel/agent/core/support/DefaultAgentPlatform.kt) — Default implementation handling action orchestration
- [`embabel-agent-api/src/main/kotlin/com/embel/agent/spi/config/spring/AgentPlatformConfiguration.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/src/main/kotlin/com/embel/agent/spi/config/spring/AgentPlatformConfiguration.kt) — Spring Boot auto-configuration

## Summary

The core purpose of embabel-agent is to provide JVM developers with:

- A **type-safe, annotation-driven framework** for building AI agents on Spring Boot
- **Pluggable planning algorithms** (GOAP, Utility AI, or custom) for dynamic goal achievement
- **Seamless mixing of code, LLM prompts, and external tools** via MCP
- **Three flexible execution modes** from focused method calls to open-ended goal discovery
- **Built-in observability and testability** for production deployments

## Frequently Asked Questions

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

embel-agent supports **Java and Kotlin** as first-class languages. All annotations (`@Agent`, `@Action`, `@AchievesGoal`) work identically in both languages, and the framework leverages Spring Boot's idiomatic patterns for each.

### How does embabel-agent differ from LangChain or other Python-based agent frameworks?

embel-agent is purpose-built for the **JVM ecosystem**, offering compile-time type safety through strongly-typed domain models, Spring dependency injection, and enterprise-grade observability. While Python frameworks dominate data science workflows, embabel-agent targets production backend systems where Java/Kotlin are prevalent.

### Can I use custom planning algorithms instead of GOAP?

Yes. The planning layer is **plugin-based**. Implement the planner interface and register your implementation with the `AgentPlatform`. The README documents this extensibility point, and [`DefaultAgentPlatform.kt`](https://github.com/embabel/embabel-agent/blob/main/DefaultAgentPlatform.kt) handles the integration.

### Is embabel-agent production-ready?

The framework includes **built-in tracing**, structured events via [`AgentPlatformEvent.kt`](https://github.com/embabel/embabel-agent/blob/main/AgentPlatformEvent.kt), and test utilities. However, as an open-source project, you should evaluate version stability and community support for your specific use case.