Skip to content

Home

Jump to bottom
Alexander Hein-Heifetz edited this page Sep 22, 2025 · 11 revisions

Welcome to Embabel Agent Wiki! 🚀

Embabel (Em-BAY-bel) is a sophisticated framework for authoring agentic flows on the JVM that seamlessly mix LLM-prompted interactions with code and domain models. Built with Kotlin and Spring Framework, it supports intelligent path finding towards goals using advanced planning algorithms.

🌟 What Makes Embabel Special?

Unlike traditional agent frameworks that rely on finite state machines or sequential execution, Embabel introduces true planning capabilities using Goal Oriented Action Planning (GOAP). This enables agents to discover novel solutions by combining existing actions in ways you never programmed.

Key Differentiators

  • 🧠 Sophisticated Planning: Goes beyond simple workflows with dynamic, non-LLM AI planning
  • 🔧 Superior Extensibility: Add capabilities without editing existing code through dynamic planning
  • 🎯 Strong Typing: Full object orientation with refactoring support and domain model behavior
  • 🌊 Platform Abstraction: Clean separation between programming model and platform internals
  • 🔄 LLM Mixing: Easy integration of different models for cost-effective, capable solutions
  • 🏗️ Spring Foundation: Built on familiar enterprise patterns with full DI and testing support

🚀 Quick Start

Get an agent running in under 5 minutes:

# Create from template (fastest)
uvx --from git+https://github.com/embabel/project-creator.git project-creator

# Or clone examples
git clone https://github.com/embabel/embabel-agent-examples
cd embabel-agent-examples/scripts/kotlin
./shell.sh

Optional: API keys enable cloud models but aren't required. Embabel works great with local models like Ollama!

📚 Navigation Guide

🎯 Get Started

📖 Core Documentation

📚 Reference & Support

🔧 Framework Development & Roadmap

🏗️ Architecture Concepts

Think of agents like master chefs in a restaurant:

  • Goals = The dish you want to prepare
  • Actions = Individual cooking techniques (chop, sauté, season)
  • Conditions = Prerequisites (ingredients fresh, pan heated)
  • Domain Model = Your ingredients, tools, and recipes
  • GOAP Planning = The chef's ability to create new recipes by combining known techniques

This allows agents to accomplish tasks they weren't explicitly programmed for by creatively combining existing capabilities.

💡 Programming Models

Annotation-Based (Spring MVC style):

@Agent(description = "Find news based on star sign")
public class StarNewsFinder {
    
    @Action
    public StarPerson extractPerson(UserInput userInput, OperationContext context) {
        return context.ai().withDefaultLlm()
            .createObject("Extract name and star sign: " + userInput);
    }
    
    @AchievesGoal(description = "Write amusing writeup")
    @Action  
    public Writeup writeup(StarPerson person, NewsStories news, OperationContext context) {
        return context.ai().withDefaultLlm()
            .createObject("Write amusing content for " + person.getName());
    }
}

Kotlin DSL (Fluent):

agent {
    action { extractPersonFromInput(it) }
    action { findRelevantNews(it) }
    goal { writeAmusingContent(it) }
}

🛠️ Development Environment

Required Setup

  • Java 21 - Oracle or OpenJDK
  • Maven - For dependency management
  • IntelliJ IDEA - Recommended IDE with Kotlin support

Optional Setup (for enhanced capabilities)

  • Docker Desktop - For MCP tools and local services
  • Ollama - For local AI models (no API keys needed!)

API Keys (Optional)

Cloud model providers enhance capabilities but aren't required:

# Optional - enables cloud models
export OPENAI_API_KEY=your_openai_key
export ANTHROPIC_API_KEY=your_anthropic_key  # Even more optional

# AWS Bedrock (requires AWS credentials)
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=your_aws_access_key
export AWS_SECRET_ACCESS_KEY=your_aws_secret_key

Docker Desktop MCP

Enable these MCP tools for full functionality:

  • Brave Search - Web search capabilities
  • Fetch - URL content retrieval
  • Puppeteer - Browser automation
  • Wikipedia - Knowledge base access

🎭 Agent Execution Modes

Focused Mode: Run specific agents with targeted input

execute("Lynda is a Scorpio, find news for her");

Closed Mode: Platform selects appropriate agent dynamically

chat("Help me plan a trip to Japan");

Open Mode: Platform uses all available goals and actions to achieve user intent

// Platform combines multiple agents and capabilities
execute("Research quantum computing and write a technical report");

🧪 Testing Philosophy

Embabel is designed for testability from the ground up:

@Test
public void shouldCreateCorrectPromptForWriteup() {
    FakeOperationContext context = new FakeOperationContext();
    context.expectResponse(new Writeup("Great day ahead!"));
    
    agent.writeup(person, news, horoscope, context);
    
    String prompt = context.getLlmInvocations().get(0).getPrompt();
    assertThat(prompt).contains(person.getName());
    assertThat(prompt).contains(horoscope.getSummary());
}

🤝 Community & Support

🎯 Real-World Example

Tripper Travel Planner - A complete travel planning agent that demonstrates:

  • Multi-step planning workflows
  • Web search integration
  • Rich domain modeling
  • Map and itinerary generation

🔮 What's Coming

  • Multi-platform support (TypeScript, Python)
  • Enhanced federation capabilities
  • Natural language actions deployment
  • Advanced reasoning models (OpenAI o1, DeepSeek R1)
  • Budget-aware agents with cost optimization

Ready to build intelligent agents? Start with our Quick Start Guide or dive into the complete documentation.

From the creator of Spring Framework - bringing enterprise-grade agent development to the JVM ecosystem.

(c) Embabel Software Inc 2024-2025.

(c) Embabel Software Inc 2024-2025.

Clone this wiki locally