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

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

@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

@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

@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
• 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 — Core runtime interface for execution modes and replanning
• 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 — 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 handles the integration.

Is embabel-agent production-ready?

The framework includes built-in tracing, structured events via AgentPlatformEvent.kt, and test utilities. However, as an open-source project, you should evaluate version stability and community support for your specific use case.

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