embabel/embabel-agent

Embabel Agent Framework – Overview

What it is – Embabel is a Java/Kotlin library for building agentic applications on the JVM. It lets you describe goals, actions, conditions, and a domain model, and the framework automatically plans and executes a sequence of actions (a plan) to achieve those goals. The planning step can use classic AI planners like GOAP or utility‑based selection, and the actions themselves can be ordinary code, calls to Spring services, or LLM‑driven prompts.

Why it matters – Most existing LLM‑agent tools are Python‑centric. Embabel brings the same ideas to the Java ecosystem, letting you reuse existing Spring‑based services, benefit from strong static typing, and keep everything testable with JUnit. It abstracts the agent runtime (focused, closed, or open modes) so you can run a single, well‑defined flow or let the platform discover novel paths across many agents.

Core Concepts

Concept	Role
Agent	A container for related goals, actions, and conditions. Declared with `@Agent` (Java) or a Kotlin DSL.
Goal	Desired end‑state. The planner tries to find a plan that satisfies it.
Action	A step the agent can perform. Implemented as a method annotated `@Action`. Can call LLMs, use tools, or run regular code.
Condition	Preconditions/post‑conditions that are re‑checked after each action.
Plan	Dynamically generated sequence of actions. Re‑planned after every step, enabling adaptation.
Domain Model	Plain Kotlin/Java objects that represent the world (e.g., `StarPerson`, `Horoscope`). All actions work with these strongly‑typed objects.

Key Features

Dynamic planning – Uses Goal‑Oriented Action Planning (GOAP) by default; also supports Utility AI. Plans are recomputed after each action, allowing the system to react to new information.
Three execution modes –
- Focused: Call a specific agent directly (code‑driven).
- Closed: Platform selects an agent based on classified intent.
- Open: Platform discovers any goal it can achieve, potentially stitching together actions from multiple agents.
Spring integration – Agents are Spring beans; you can inject services, use AOP, and leverage Spring’s transaction and persistence support.
Strong typing – Actions receive and return concrete domain objects; prompts are built with type‑safe APIs, avoiding “magic maps”.
Extensible planning – Plug‑in your own planner if GOAP/Utility AI don’t fit.
Testability – Unit‑test actions like any Spring component; end‑to‑end agent tests are also supported.
LLM mixing – Easily combine multiple models (e.g., cheap local model for simple tasks, OpenAI for creative steps) within the same flow.
Tool groups – Declare required external tools (e.g., web search) per action via toolGroups annotation.

Typical Use Cases

Enterprise workflows where existing Java services need to be orchestrated with LLM‑generated content (e.g., personalized emails, report generation).
Customer‑facing agents that combine knowledge‑base look‑ups, external APIs, and LLM reasoning.
Automation bots that plan multi‑step tasks such as travel planning, document processing, or data enrichment.
Research prototypes exploring dynamic planning, utility‑based decision making, or federated agent networks on the JVM.

Getting Started

Create a project – Use the provided templates:
- Java: https://github.com/embabel/java-agent-template
- Kotlin: https://github.com/embabel/kotlin-agent-template

Add the dependency (Maven Central):

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-api</artifactId>
    <version>1.5.0‑SNAPSHOT</version>
</dependency>

Define an agent – Annotate a Spring bean with @Agent and add @Goal, @Condition, @Action methods (see the README’s Java/Kotlin examples).
Run – Choose a platform mode (Focused, Closed, Open) via AgentPlatform bean and invoke runAgent(...) or let the platform dispatch based on user intent.
Explore examples –
- General examples: https://github.com/embabel/embabel-agent-examples
- Full‑featured travel planner: https://github.com/embabel/tripper

Ecosystem & Compatibility

Built on Spring Boot – Works with any Spring Boot version; you can inject other Spring components (repositories, REST clients, etc.).
JVM languages – Core library is Kotlin, but the API is fully usable from Java.
Tool integrations – The framework defines tool groups (e.g., WEB) that can be wired to concrete implementations (search APIs, databases, etc.).
LLM back‑ends – Uses Spring AI under the hood, so any model supported by Spring AI (OpenAI, Azure, local Ollama, etc.) can be swapped in.
Containerisation – Docker images are provided for the platform; CI/CD pipelines use GitHub Actions and SonarQube for quality.

License & Community

License – Apache 2.0 (per badge in README).
Community – Discord channel, live documentation site, and issue tracker on GitHub. Continuous integration status, SonarQube quality gate, and Maven Central publishing indicate an actively maintained project.

Bottom line – Embabel gives Java/Kotlin developers a high‑level, testable way to build LLM‑augmented agents that can plan, adapt, and reuse existing enterprise code. It fills the gap for JVM‑centric AI agents while staying compatible with the broader Spring ecosystem.