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

Tools Concept

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

Tools expose operations to LLMs for function-calling/tool-use during agent execution.

LLM Tools

Expose methods as LLM-callable tools:

@EmbabelComponent
public class FileTools {

    @LlmTool(description = "Read file contents", name = "read_file")
    public String readFile(
        @LlmTool.Param(description = "File path", required = true) String path
    ) {
        return Files.readString(Path.of(path));
    }

    @LlmTool(description = "Write file", returnDirect = true)
    public void writeFile(
        @LlmTool.Param(description = "File path") String path,
        @LlmTool.Param(description = "Content") String content
    ) {
        Files.writeString(Path.of(path), content);
    }
}

Programmatic Tools

Create tools dynamically:

List<Tool> tools = List.of(
    Tool.create("add", "Add numbers", this::add),
    Tool.create("multiply", "Multiply numbers", this::multiply),
    Tool.fromMethod(this, method)
);

Matryoshka Tools (Progressive Disclosure)

Group tools by category to reduce initial complexity:

@EmbabelComponent
@MatryoshkaTools(
    name = "database_ops",
    description = "Database operations - select category: query, insert, update, delete",
    removeOnInvoke = true
)
public class DatabaseTools {

    @LlmTool(description = "Execute SELECT query", category = "query")
    public List<Map<String, Object>> select(@LlmTool.Param(description = "SQL") String sql) { }

    @LlmTool(description = "Insert record", category = "insert")
    public int insert(
        @LlmTool.Param(description = "Table") String table,
        @LlmTool.Param(description = "Data") Map<String, Object> data
    ) { }

    @LlmTool(description = "Update record", category = "update")
    public int update(String table, String where, Map<String, Object> data) { }

    @LlmTool(description = "Delete record", category = "delete")
    public int delete(String table, String where) { }
}

LLM first sees only "database_ops" tool with categories, then specific tools after category selection.

Agentic Tools

Wrap agents as tools:

List<Tool> tools = List.of(
    AgenticTool.fromAgent(DataAnalyzerAgent.class),
    AgenticTool.fromAgent("ValidationAgent"),
    AgenticTool.fromAgent(agentInstance)
);

Tool Groups

Organize and manage related tools:

@EmbabelComponent
public class AnalysisTools {

    @ToolGroup(role = "statistical-analysis")
    public List<Tool> getStatTools() {
        return List.of(
            Tool.create("mean", "Calculate mean", this::calculateMean),
            Tool.create("median", "Calculate median", this::calculateMedian),
            Tool.create("std_dev", "Standard deviation", this::stdDev)
        );
    }
}

Actions can require tool groups:

@Action(
    description = "Statistical analysis",
    toolGroupRequirements = {"statistical-analysis"}
)
public Report analyze(Data data, @Provided Ai ai) {
    return ai.createObject("Analyze: " + data);
}

Using Tools in Actions

@Action(description = "Process with custom tools")
public Result process(Input input, @Provided Ai ai) {
    List<Tool> tools = List.of(
        Tool.create("validate", this::validate),
        MatryoshkaTool.fromInstance(new DataTransforms()),
        AgenticTool.fromAgent(EnrichmentAgent.class)
    );

    return ai.withLlm(OpenAiModels.GPT_4_TURBO)
             .withTools(tools)
             .createObject("Process: " + input);
}

Best Practices

Clear, specific tool descriptions for LLM understanding
Use MatryoshkaTools for large tool sets (>10 tools)
Document all parameters with @LlmTool.Param
Group related tools with @ToolGroup
Use returnDirect = true for tools that need no LLM processing
Validate tool inputs before processing
Return meaningful errors from tool execution

See Also: Actions | API Reference | Guide: Creating Tools

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