# Embabel-Agent Architecture Modules Explained: A Complete Guide to 14 Core Components

> Explore the embabel-agent architecture and its 14 core modules. Understand APIs, LLM integrations, RAG pipelines, and more with this comprehensive guide.

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

---

**The embabel-agent project is organized into 14 distinct Maven modules spanning core APIs, auto-configuration, LLM integrations, RAG pipelines, and interactive shells.**

This article breaks down every module in the [embabel/embabel-agent](https://github.com/embabel/embabel-agent) architecture, explaining how each component fits together and which ones you need for your use case. Whether you're building a CLI agent, a web service, or a retrieval-augmented system, understanding these modules helps you assemble a minimal, production-ready stack.

---

## Core Foundation: embabel-agent-api

The **embabel-agent-api** module defines the essential abstractions that everything else builds upon.

It contains:
- The **agent model** (`Agent`, `Goal`, `Action`, `Blackboard`)
- **Planning primitives** for goal decomposition and execution
- **Configuration properties** and the public **SPI** (Service Provider Interface)

This module can be used standalone without any UI or tooling dependencies. According to the source code in `com.embabel.agent.*`, it establishes the property segregation principle that keeps framework internals separate from user-defined configurations.

---

## Configuration and Bootstrapping

### embabel-agent-autoconfigure

The **embabel-agent-autoconfigure** module provides Spring Boot auto-configuration that eliminates boilerplate. It watches for annotations like `@EnableAgentShell` and `@EnableAgents`, then activates the appropriate profiles and registers beans automatically.

The key class `AgentPlatformAutoConfiguration` (located in `com.embabel.agent.autoconfigure.*`) boots the platform, tools group, and RAG services. For early profile activation, the `EmbabelEnvironmentPostProcessor` runs before most other Spring components.

### embabel-agent-dependencies

This **BOM (Bill-of-Materials)** module aggregates third-party dependency versions across the entire project. Import it to ensure consistent versions without managing individual dependencies.

---

## User Interfaces and Interaction Layers

### embabel-agent-shell

The **embel-agent-shell** module delivers an interactive CLI built on Spring Shell. It provides commands including:

- `agents` – list and manage running agents
- `chat` – conversational interface
- `execute` – run specific goals or actions
- Themed prompts (Star Wars, default, etc.)

Key files include [`ShellCommands.kt`](https://github.com/embabel/embabel-agent/blob/main/ShellCommands.kt) and [`TerminalServices.kt`](https://github.com/embabel/embabel-agent/blob/main/TerminalServices.kt) in the shell source tree. Activate it with `@EnableAgentShell` and the `embabel-agent-starter-shell` dependency.

### embabel-agent-common

The **embabel-agent-common** module houses shared infrastructure:

- `embabel-agent-webmvc` – REST controllers and SSE streaming
- `embel-agent-byok` – bring-your-own-key abstractions
- `embabel-agent-ai` – generic AI service interfaces

Web-focused applications pull from this module to expose agents via HTTP endpoints.

### embabel-agent-mcp

The **Model-Control-Plane** server implementation exposes a REST API for managing models, datasets, and execution environments. It splits into:

- `embabel-agent-mcpserver` – core control plane
- `embel-agent-mcp-security` – authentication and authorization

---

## LLM Provider Integrations

### embabel-agent-openai

Full integration with OpenAI models, including:

- Option conversion between Embabel and OpenAI formats
- `OpenAiCompatibleModelFactory` for model instantiation
- BYOK (bring-your-own-key) support

Package: `com.embabel.agent.openai.*`

### embabel-agent-anthropic

Mirrors the OpenAI module structure for **Anthropic Claude** models. Same capabilities, different provider.

Package: `com.embel.agent.anthropic.*`

### embabel-agent-onnx

**ONNX-based inference** for locally-hosted models without external API dependencies. Ideal for air-gapped or latency-sensitive deployments.

Package: `com.embel.agent.onnx.*`

---

## Retrieval-Augmented Generation: embabel-agent-rag

The **embabel-agent-rag** module splits into four focused sub-modules:

| Sub-module | Purpose |
|------------|---------|
| `rag-core` | Pipeline abstractions and the `RagPipeline` builder |
| `rag-pipeline` | Orchestration logic for query → retrieve → generate |
| `rag-lucene` | Lucene-based vector and keyword retrieval |
| `rag-tika` | Apache Tika integration for document parsing |

Swap retrievers and generators by changing injected beans—no code changes required.

Example usage:

```kotlin
val rag = RagPipeline.builder()
    .retriever(LuceneRetriever())
    .generator(OpenAiChatModel())
    .build()

val answer = rag.ask("What is the latest news about Kotlin?")

```

---

## Advanced Capabilities

### embabel-agent-a2a

**Agent-to-Agent** integration enables agents to invoke other agents and exchange intents. This composability lets you build multi-agent systems where specialized agents delegate to each other.

Package: `com.embel.agent.a2a`

### embabel-agent-skills

Pre-built **skill libraries** that agents can invoke:

- Tool groups for common operations
- Form handling and validation
- Extensible skill packs in `embel-agent-skills/*`

### embabel-agent-code

Developer productivity utilities for **generating source code**, documentation snippets, and other artifacts from agent outputs.

Package: `com.embel.agent.codegen`

### embabel-agent-observability

Instrumentation layer integrating **Micrometer, Zipkin, and OpenTelemetry**. Through Spring AOP, it emits tracing events for:

- Every planning step
- Model calls
- Tool executions

Key file: [`EmbeddingSpanEventListener.java`](https://github.com/embabel/embabel-agent/blob/main/EmbeddingSpanEventListener.java) demonstrates the tracing integration pattern.

---

## Testing and Development Support

### embabel-agent-test-support

Helper utilities and test harnesses used by the extensive test suite. Includes mocks, fixtures, and assertion helpers.

Artifacts: `embel-agent-test*`

### embabel-agent-starters

**Spring Boot starter POMs** bundle minimal dependency sets for common use cases:

| Starter | Includes |
|---------|----------|
| `embel-agent-starter-shell` | Shell + Core API |
| `embel-agent-starter-webmvc` | Web MVC + Common |
| `embel-agent-starter-observability` | Metrics + Tracing |
| `embel-agent-starter-openai` | OpenAI integration |
| `embel-agent-starter-anthropic` | Anthropic integration |
| `embel-agent-starter-ollama` | Ollama local models |

---

## How the Modules Connect

The architecture follows a layered dependency flow:

1. **Foundation** – `embel-agent-api` defines contracts
2. **Configuration** – `embel-agent-autoconfigure` wires implementations based on starters and annotations
3. **Execution** – Shell, Web MVC, or MCP modules expose the runtime
4. **Intelligence** – Provider modules (OpenAI, Anthropic, ONNX) and RAG plug into the core SPI
5. **Observability** – Cross-cutting instrumentation via AOP
6. **Extensibility** – Skills and starters enable composition without code duplication

---

## Code Example: Minimal Shell Application

```kotlin
// src/main/kotlin/com/example/ShellApp.kt
@SpringBootApplication
@EnableAgentShell
class ShellApp

fun main(args: Array<String>) = runApplication<ShellApp>(*args)

```

With `embel-agent-starter-shell` on the classpath, this activates:
- `ShellConfiguration`
- `ShellCommands`
- Default prompt provider

---

## Code Example: OpenAI-Enabled Agent

```java
// src/main/java/com/example/OpenAiApp.java
@SpringBootApplication
@EnableAgents(
    localModels = { LocalModels.OPENAI },
    loggingTheme = LoggingThemes.STAR_WARS
)
public class OpenAiApp {
    public static void main(String[] args) {
        SpringApplication.run(OpenAiApp.class, args);
    }
}

```

The `@EnableAgents` annotation activates the `openai` profile and registers `OpenAiCompatibleModelFactory`.

---

## Summary

- **14 top-level modules** compose the embabel-agent architecture, declared in the root [`pom.xml`](https://github.com/embabel/embabel-agent/blob/main/pom.xml)
- **embel-agent-api** provides the foundational abstractions every other module depends on
- **Auto-configuration** via `@EnableAgentShell` and `@EnableAgents` eliminates manual bean wiring
- **Provider modules** (OpenAI, Anthropic, ONNX) implement the same SPI for interchangeable LLM backends
- **RAG pipeline** splits into core, pipeline, Lucene, and Tika sub-modules for flexible retrieval
- **Starters** and **skills** enable lean, purpose-built agent assemblies

---

## Frequently Asked Questions

### What is the minimum set of modules needed for a working agent?

You need **embel-agent-api** for core abstractions, **embel-agent-autoconfigure** for Spring Boot integration, and at least one provider module (e.g., **embel-agent-openai**) or **embel-agent-onnx** for local inference. Add **embel-agent-starter-shell** for CLI interaction or **embel-agent-common** for web endpoints.

### How do I switch from OpenAI to Anthropic without code changes?

Both providers implement the same SPI from **embel-agent-api**. Change your starter dependency from `embel-agent-starter-openai` to `embel-agent-starter-anthropic`, and update `@EnableAgents(localModels = { LocalModels.ANTHROPIC })`. The auto-configuration handles the rest.

### Where are the module declarations located?

All modules are enumerated in the `<module>` elements of the root [`pom.xml`](https://github.com/embabel/embabel-agent/blob/main/pom.xml) at the repository root. This is the authoritative source for the project structure.

### Can I use the RAG modules without Spring Boot?

Yes. The **embel-agent-rag-core** and **embel-agent-rag-pipeline** modules have minimal Spring dependencies. You can instantiate `RagPipeline` directly with your own dependency injection or manual construction, as shown in the builder example above.

### What distinguishes embabel-agent-shell from embabel-agent-mcp?

**embel-agent-shell** provides an **interactive CLI** for local development and operations. **embel-agent-mcp** exposes a **REST control plane** for remote model management, dataset operations, and execution environment control—designed for production deployments and multi-tenant scenarios.