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

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

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

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

// 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
• 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 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.

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