Quick Start Guide

Quick Start Guide

Get your first Embabel agent running in under 5 minutes!

Prerequisites

• Java 21 (Oracle or OpenJDK)
• Maven 3.6+
• IntelliJ IDEA (recommended)

Optional (for enhanced capabilities):

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

Step 1: Create Your Project

Option A: Using Project Creator (Recommended)

uvx --from git+https://github.com/embabel/project-creator.git project-creator

Choose Kotlin when prompted, specify your project details, and you'll have a working agent in under a minute!

Option B: Clone Examples Repository

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

Option C: Use GitHub Templates

• Kotlin Template - Click "Use this template"
• Java Template - Click "Use this template"

Step 2: Set Up Environment (Optional)

Local Models (Recommended for Getting Started)

No API keys needed! Install Ollama for local AI:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model (choose one)
ollama pull llama3.2          # General purpose
ollama pull codellama          # Code-focused
ollama pull llama3.2:1b        # Lightweight

# Start Ollama server
ollama serve

Cloud Models (Optional)

Enhance capabilities with cloud providers:

# Optional - enables advanced cloud models
export OPENAI_API_KEY=your_openai_api_key

# Even more optional - enables Claude models
export ANTHROPIC_API_KEY=your_anthropic_api_key

# 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

# For examples that demonstrate cloud features
export EMBABEL_API_KEY=brahmsian

Note: Embabel works great without any API keys using local models!

Step 3: Run Your First Agent

Using Shell Interface

# Start the interactive shell
mvn spring-boot:run -Dspring-boot.run.profiles=shell

# Try these commands:
help
execute "Lynda is a Scorpio, find news for her" -p -r
chat

Example Commands

# Fact checking agent
x "fact check: holden cars are still made in australia"

# Research agent (requires web tools)
execute "research the recent australian federal election"

# Travel planning
x "plan a 3-day trip to Kyoto for someone interested in temples and food"

Step 4: Explore the Code

Your generated project includes:

Domain Objects (DDD Style)

public record StarPerson(
    String name,
    @JsonPropertyDescription("Star sign") 
    String sign
) implements Person {}

Agent Implementation

@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, StarPerson.class);
    }
    
    @AchievesGoal(description = "Write amusing news writeup")
    @Action(toolGroups = {ToolGroup.WEB})
    public Writeup writeup(StarPerson person, OperationContext context) {
        return context.ai().withDefaultLlm()
            .createObject(String.format("""
                Find news relevant to %s (%s) 
                and write an amusing summary.
                """, person.name(), person.sign()), Writeup.class);
    }
}

Testing Your Agent

@Test
public void shouldExtractPersonCorrectly() {
    FakeOperationContext context = new FakeOperationContext();
    context.expectResponse(new StarPerson("Alice", "Leo"));
    
    StarPerson result = agent.extractPerson(
        new UserInput("I'm Alice and I'm a Leo"), context);
    
    assertThat(result.name()).isEqualTo("Alice");
    assertThat(result.sign()).isEqualTo("Leo");
}

Step 5: Enable Docker Desktop MCP (Optional)

For web search and advanced capabilities:

1. Install Docker Desktop with MCP extension

2. Enable these tools from the MCP catalog:

   • Brave Search
   • Fetch
   • Puppeteer
   • Wikipedia

3. Run with Docker profile:

mvn spring-boot:run -Dspring-boot.run.profiles=docker-desktop

Common Shell Commands

# Execute specific agents
execute "your request here" -p -r
x "shorter version of execute"

# Interactive chat mode
chat

# Get help
help

# View available commands
help execute
help chat

# Exit
exit

Command Options

• -p - Log prompts sent to LLMs
• -r - Log responses from LLMs
• -v - Verbose logging

Next Steps

1. Explore Examples - More complex use cases
2. Read Core Concepts - Understand Goals, Actions, and GOAP
3. Try Tripper - Complete travel planning application
4. Join Discord - Get help from the community

Troubleshooting

Common Issues

No valid OpenAI API key:

export OPENAI_API_KEY=sk-your-key-here

Shell doesn't start:

# Make sure you're using the shell profile
mvn spring-boot:run -Dspring-boot.run.profiles=shell

Web tools not working:

• Enable Docker Desktop MCP extension
• Use the docker-desktop profile

Maven build fails:

• Ensure Java 21 is installed and JAVA_HOME is set
• Check that Maven 3.6+ is available

Getting Help

• Discord Community - Real-time support
• GitHub Issues - Bug reports
• GitHub Discussions - Questions and ideas

---

🎉 Congratulations! You now have a working Embabel agent. The framework's GOAP planning system can combine your actions in novel ways to achieve complex goals.