CtrlK

Community Documentation Log in Get started

tessl/maven-com-embabel-agent--embabel-agent-starter

Base starter module for the Embabel Agent Framework providing core dependencies for building agentic flows on the JVM with Spring Boot integration and GOAP-based intelligent path finding.

Overview

Eval results

Files

Component Scanning Reference

Name: tessl/maven-com-embabel-agent--embabel-agent-starter
Author: tessl

Complete reference for Spring component scanning configuration and package structure.

Auto-Scanned Packages

The starter automatically scans these packages:

Package	Purpose
`com.embabel.agent.api`	Core agent API components and interfaces
`com.embabel.agent.core`	Core implementation classes and services
`com.embabel.agent.experimental`	Experimental features (may change)
`com.embabel.agent.prompt`	Prompt-related components and templates
`com.embabel.agent.spi`	Service Provider Interface implementations
`com.embabel.agent.test`	Testing support components and utilities
`com.embabel.agent.tools`	Tool implementations for agent use
`com.embabel.agent.web`	Web-related components (REST, SSE, etc.)

ScanConfiguration Class

@Configuration
@ComponentScan(basePackages = {
    "com.embabel.agent.api",
    "com.embabel.agent.core",
    "com.embabel.agent.experimental",
    "com.embabel.agent.prompt",
    "com.embabel.agent.spi",
    "com.embabel.agent.test",
    "com.embabel.agent.tools",
    "com.embabel.agent.web"
})
@EnableConfigurationProperties
public class ScanConfiguration {
    // Enables component scanning and configuration properties
}

Scanning Configuration Properties

Property	Type	Default	Description
`embabel.agent.platform.scanning.annotation`	boolean	`true`	Enable `@Agent`/`@Agentic` annotation scanning
`embabel.agent.platform.scanning.bean`	boolean	`false`	Enable bean-based agent scanning

embabel:
  agent:
    platform:
      scanning:
        annotation: true
        bean: false

Agent Component Examples

Java Agent

package com.embabel.agent.api.agents;

import com.embabel.agent.api.annotation.Agent;
import com.embabel.agent.api.annotation.Action;
import org.springframework.stereotype.Component;

@Agent(description = "Customer service agent")
@Component
public class CustomerServiceAgent {

    @Action
    public Response handleRequest(Request request) {
        // Implementation
    }
}

Kotlin Agent

package com.embabel.agent.api.agents

import com.embabel.agent.api.annotation.Agent
import com.embabel.agent.api.annotation.Action
import org.springframework.stereotype.Component

@Agent(description = "Data processing agent")
@Component
class DataProcessingAgent {

    @Action
    fun processData(input: Input): Result {
        // Implementation
    }
}

Custom Package Scanning

Add Custom Packages

package com.mycompany.myapp;

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

@Configuration
@ComponentScan(basePackages = {
    "com.mycompany.myapp.agents",
    "com.mycompany.myapp.services"
})
public class MyAppScanConfiguration {
    // Custom packages will be scanned
}

Kotlin Configuration

package com.mycompany.myapp

import org.springframework.context.annotation.ComponentScan
import org.springframework.context.annotation.Configuration

@Configuration
@ComponentScan(basePackages = [
    "com.mycompany.myapp.agents",
    "com.mycompany.myapp.services"
])
class MyAppScanConfiguration

Recommended Package Structure

src/main/
├── java/ (or kotlin/)
│   └── com/
│       └── embabel/
│           └── agent/
│               └── api/
│                   └── myapp/
│                       ├── agents/
│                       │   ├── CustomerAgent.java
│                       │   └── DataAgent.java
│                       ├── config/
│                       │   └── MyAppProperties.java
│                       └── services/
│                           └── MyService.java
└── resources/
    └── application.yml

Conditional Scanning

@ConditionalOnProperty

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.stereotype.Component;

@Component
@ConditionalOnProperty(name = "myapp.feature.enabled", havingValue = "true")
public class OptionalAgent {
    // Only discovered when property is set to true
}

@ConditionalOnMcpConnection

import com.embabel.agent.spi.config.spring.ConditionalOnMcpConnection;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MyToolsConfiguration {

    @Bean
    @ConditionalOnMcpConnection("github-mcp")
    public ToolGroup githubTools() {
        // Only created when github-mcp connection is configured
        return ToolGroup.create("github", githubToolList);
    }

    @Bean
    @ConditionalOnMcpConnection("brave-search-mcp", "fetch-mcp")
    public ToolGroup webTools() {
        // Created when ANY of the specified connections exists
        return ToolGroup.create("web", webToolList);
    }
}

Annotation definition:

@Target(AnnotationTarget.FUNCTION, AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
@MustBeDocumented
@Conditional(OnMcpConnectionCondition::class)
annotation class ConditionalOnMcpConnection(
    vararg val value: String
)

Configuration check:

spring:
  ai:
    mcp:
      client:
        stdio:
          connections:
            github-mcp:
              command: npx
              args:
                - -y
                - "@modelcontextprotocol/server-github"

Exclusion Filters

Exclude Specific Packages

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.FilterType;

@Configuration
@ComponentScan(
    basePackages = "com.embabel.agent.api",
    excludeFilters = @ComponentScan.Filter(
        type = FilterType.REGEX,
        pattern = "com\\.embabel\\.agent\\.api\\.experimental\\..*"
    )
)
public class CustomScanConfiguration {
    // Excludes experimental package
}

Exclude Specific Classes

@Configuration
@ComponentScan(
    basePackages = "com.embabel.agent.api",
    excludeFilters = @ComponentScan.Filter(
        type = FilterType.ASSIGNABLE_TYPE,
        classes = {UnwantedAgent.class, TestAgent.class}
    )
)
public class FilteredScanConfiguration {
    // Excludes specific classes
}

Configuration Properties Scanning

package com.embabel.agent.api.config;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "myapp.agent")
public class MyAgentProperties {
    private String apiKey;
    private int maxRetries = 3;

    // Getters and setters
}

Discovery Types

Components discovered through scanning:

Agent Classes - Classes annotated with @Agent and @Component
Action Methods - Methods annotated with @Action within agent classes
Goal Achievements - Methods annotated with @AchievesGoal
Tool Implementations - Classes implementing tool interfaces with @Component
Services - Classes annotated with @Service providing agent functionality
Configuration Classes - Classes annotated with @Configuration for bean definitions
Configuration Properties - Classes annotated with @ConfigurationProperties

Built-in Tool Groups

Tool groups using @ConditionalOnMcpConnection:

Tool Group	MCP Connection(s)	Purpose
`mathToolGroup`	(none, always created)	Math operations
`mcpWebToolsGroup`	`brave-search-mcp`, `fetch-mcp`, `wikipedia-mcp`, `docker-mcp`	Web tools
`mapsToolsGroup`	`google-maps-mcp`, `docker-mcp`	Maps tools
`browserAutomationWebToolsGroup`	`puppeteer-mcp`, `docker-mcp`	Browser automation
`githubToolsGroup`	`github-mcp`, `docker-mcp`	GitHub tools

Dependency Injection

Constructor Injection (Recommended)

import com.embabel.agent.api.platform.AgentPlatform;
import org.springframework.stereotype.Component;

@Component
public class MyService {
    private final AgentPlatform platform;

    public MyService(AgentPlatform platform) {
        this.platform = platform;
    }

    public void runAgent() {
        platform.execute(/* ... */);
    }
}

Field Injection (Not Recommended)

@Component
public class MyService {
    @Autowired
    private AgentPlatform platform;
}

Circular Dependency Resolution

@Component
public class ServiceA {
    private final ServiceB serviceB;

    public ServiceA(@Lazy ServiceB serviceB) {
        this.serviceB = serviceB;
    }
}

Testing with Component Scanning

import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SpringExtension.class)
@SpringBootTest
public class AgentScanningTest {

    @Autowired
    private ApplicationContext context;

    @Test
    public void testAgentDiscovery() {
        Map<String, Object> agents = context.getBeansWithAnnotation(Agent.class);
        assertTrue(agents.size() > 0);
    }
}

Performance Configuration

Enable Lazy Initialization

spring:
  main:
    lazy-initialization: true

Debug Logging

logging:
  level:
    org.springframework.context.annotation: DEBUG

Environment Variable Overrides

# Enable annotation scanning
export EMBABEL_AGENT_PLATFORM_SCANNING_ANNOTATION=true

# Enable bean scanning
export EMBABEL_AGENT_PLATFORM_SCANNING_BEAN=false

Complete Configuration Example

# application.yml
embabel:
  agent:
    platform:
      scanning:
        annotation: true
        bean: false

spring:
  main:
    lazy-initialization: false

logging:
  level:
    com.embabel.agent: INFO
    org.springframework.context.annotation: WARN

tessl i tessl/maven-com-embabel-agent--embabel-agent-starter@0.3.1