Agents Concept

Agents are autonomous components that achieve goals through planning and action execution using GOAP (Goal-Oriented Action Planning).

Definition

@Agent(
    description = "Agent purpose",           // Required
    planner = PlannerType.GOAP,             // Planning algorithm
    version = "1.0.0",                      // Agent version
    actionRetryPolicy = ActionRetryPolicy.exponential(3, 1000)
)
@Component
public class MyAgent {
    // Actions and conditions
}

Key Attributes

• description (required): Agent purpose
• planner: Planning algorithm (default: GOAP)
• scan: Enable scanning for actions/conditions (default: true)
• opaque: Hide internal details when used as subagent (default: false)
• actionRetryPolicy: Default retry strategy for actions
• provider: Namespace for organizing agents
• beanName: Override Spring bean name

Planning

GOAP planner:

• Evaluates action preconditions and postconditions
• Uses cost and value to select optimal action sequence
• Dynamically adapts based on blackboard state

Agent Types

Regular Agent: Full GOAP planning with actions and conditions

@Agent(description = "Data processor", planner = PlannerType.GOAP)
public class DataAgent {
    @Action(description = "Load data", post = {"dataLoaded"})
    public Data loadData(String source) { }

    @Action(description = "Process data", pre = {"dataLoaded"})
    public Result process(Data data) { }
}

Component: Provides capabilities without being a full agent

@EmbabelComponent(scan = true)
public class FileOperations {
    @Action(description = "Read file")
    public String readFile(String path) { }
}

Subagents

Agents can invoke other agents:

@Action(description = "Delegate to subagent")
public Result delegateWork(Input input, @Provided AgentPlatform platform) {
    Subagent subagent = new Subagent("SpecializedAgent");
    Agent resolved = subagent.resolve(platform);
    return invokeSubagent(resolved, input);
}

Best Practices

1. Clear, specific descriptions for LLM understanding
2. Use GOAP for complex multi-step workflows
3. Set appropriate retry policies per action criticality
4. Mark internal agents as opaque when used as subagents
5. Place agents in scanned packages (com.embabel.agent.*) for auto-discovery

See Also: Actions | Goals | API Reference