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

Invocation Concept

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

Agent invocation is the programmatic interface for executing agents and receiving typed results.

Basic Invocation

@Service
public class MyService {
    private final AgentPlatform platform;

    public OrderResult processOrder(Order order) {
        AgentInvocation<OrderResult> invocation =
            AgentInvocation.create(platform, OrderResult.class);
        return invocation.invoke(order);
    }
}

Kotlin with reified generics:

val invocation = AgentInvocation.create<OrderResult>(platform)
val result = invocation.invoke(order)

Builder Pattern

For advanced configuration:

AgentInvocation<AnalysisResult> invocation = AgentInvocation.builder(platform)
    .withContext(new ExecutionContext("session-id"))
    .withBlackboard(Blackboard.fromMap(initialState))
    .withVerbosity(Verbosity.DETAILED)
    .withBudget(Budget.of(120, TimeUnit.SECONDS))
    .withPolicies(PolicySet.builder()
        .withRetryPolicy(RetryPolicy.exponential(3, 1000))
        .withTimeoutPolicy(TimeoutPolicy.of(90, TimeUnit.SECONDS))
        .build())
    .build(AnalysisResult.class);

AnalysisResult result = invocation.invoke(dataset);

Async Invocation

CompletableFuture<Report> future = invocation.invokeAsync(data)
    .thenApply(this::postProcess)
    .exceptionally(this::handleError);

Specialized Invocations

Utility Invocation

For simple utility agents without GOAP planning:

UtilityInvocation<String> invocation =
    UtilityInvocation.create(platform, String.class);
String result = invocation.invoke(input);

Supervisor Invocation

For agents coordinating multiple subagents:

SupervisorInvocation<WorkflowResult> invocation =
    SupervisorInvocation.create(platform, WorkflowResult.class);
WorkflowResult result = invocation.invoke(workflowSpec);

Scoped Invocation

For isolated execution contexts:

val invocation = ScopedInvocation.create<Result>(platform)
    .withScope("isolated-execution")
val result = invocation.invoke(input)

Execution Context

Available in actions via @Provided ActionContext:

@Action(description = "Process with progress tracking")
public Result process(Input input, @Provided ActionContext context) {
    context.updateProgress("Loading data...");
    context.sendMessage(Message.info("Processing " + input.size() + " items"));

    // Execute subprocess
    DetailedResult detailed = context.asSubProcess(
        DetailedResult.class,
        DetailedAnalyzerAgent.class
    );

    context.updateProgress("Complete!");
    return createResult(detailed);
}

Blackboard

Shared state accessible to all actions:

Map<String, Object> initialState = Map.of(
    "config", configObject,
    "credentials", credentials,
    "userId", userId
);

AgentInvocation<Result> invocation = AgentInvocation.builder(platform)
    .withBlackboard(Blackboard.fromMap(initialState))
    .build(Result.class);

Actions retrieve from blackboard:

@Action(description = "Use config from blackboard")
public Result useConfig(Config config, String userId) {
    // 'config' and 'userId' from blackboard
}

Budget Control

Time-based:

.withBudget(Budget.of(60, TimeUnit.SECONDS))

Step-based:

.withBudget(Budget.ofSteps(1000))

Unlimited:

.withBudget(Budget.unlimited())

Verbosity Levels

.withVerbosity(Verbosity.SILENT)   // No logging
.withVerbosity(Verbosity.MINIMAL)  // Errors only
.withVerbosity(Verbosity.NORMAL)   // Standard logging (default)
.withVerbosity(Verbosity.DETAILED) // Detailed execution trace
.withVerbosity(Verbosity.DEBUG)    // Full debug output

Subagent Management

Reference and resolve subagents:

@Action(description = "Delegate to subagents")
public Result delegate(Input input, @Provided AgentPlatform platform) {
    Subagent validator = new Subagent("ValidationAgent");
    Subagent transformer = new Subagent(TransformerAgent.class);

    Agent validatorAgent = validator.resolve(platform);
    Agent transformerAgent = transformer.resolve(platform);

    ValidationResult validated = invokeSubagent(validatorAgent, input);
    return invokeSubagent(transformerAgent, validated);
}

Best Practices

Use typed invocations for compile-time safety
Set reasonable budgets to prevent runaway execution
Initialize blackboard for complex agent state
Use builder pattern for advanced configuration
Handle async errors with exceptionally()
Use appropriate verbosity for environment
Track progress in long-running actions
Scope subagents properly for clean composition

See Also: Actions | Goals | API Reference

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