feat(agentic): Phase 4 — BOM and Integration

[jwijgerd]

Phase 4: BOM and Integration

Tracking issue: #284
Modules: bom/, main/pom.xml, main/eventcatalog
Can start: After Phase 2 (#286) and Phase 3 (#287) are merged
⚠️ Cannot run concurrently: This phase requires both Phase 2 and Phase 3 to be complete

Plan reference: plans/agentic-aggregates.md → Phase 4: BOM and Integration

---

Overview

Integrate the new akces-agentic module into the build system, BOM, and documentation tooling. Update the EventCatalog annotation processor to support @AgenticAggregateInfo, and update framework documentation.

---

Tasks

1. Add akces-agentic to the BOM

Edit bom/pom.xml to add the new module alongside the existing managed dependencies:

<dependency>
    <groupId>org.elasticsoftwarefoundation.akces</groupId>
    <artifactId>akces-agentic</artifactId>
    <version>${project.version}</version>
</dependency>

This allows consumers of the Akces BOM to include akces-agentic without specifying a version.

2. Add main/agentic to Parent POM

Edit main/pom.xml to add agentic to the <modules> section so it is built as part of the standard mvn install lifecycle:

<module>agentic</module>

Place it after runtime in the module list (since agentic depends on runtime).

3. Update EventCatalog Annotation Processor

The main/eventcatalog annotation processor generates EventCatalog-compatible documentation by scanning annotations at compile time. Extend it to support @AgenticAggregateInfo:

• Detect classes annotated with @AgenticAggregateInfo
• Extract: value (aggregate name), description, stateClass, maxMemories
• Generate EventCatalog output entries for AgenticAggregates (similar to how @AggregateInfo is handled)
• Include the built-in memory commands (StoreMemoryCommand, ForgetMemoryCommand) and events (MemoryStoredEvent, MemoryRevokedEvent) in the generated docs
• Mark the aggregate as a Singleton type in the documentation (distinguishing it from normal aggregates)

4. Update Framework Documentation

Update the following documentation files to cover the AgenticAggregate concept:

• README.md — Add a brief mention of AgenticAggregates and link to the full documentation
• FRAMEWORK_OVERVIEW.md — Add a section on AgenticAggregates: what they are, when to use them, and how they differ from normal aggregates
• SERVICES.md — Document the new AgenticAggregate Kubernetes CRD:
  • CRD kind and short name (aag)
  • Spec fields (image, applicationName, sidecars, env, etc.)
  • Example CR with GitHub MCP Server sidecar
  • Note that replicas are always 1

---

Acceptance Criteria

• bom/pom.xml includes akces-agentic as a managed dependency
• main/pom.xml <modules> section includes agentic (ordered after runtime)
• mvn install from main/ root compiles and tests all modules including agentic
• EventCatalog annotation processor correctly processes @AgenticAggregateInfo-annotated classes
• Generated EventCatalog output includes built-in memory commands and events
• AgenticAggregate documented in README.md, FRAMEWORK_OVERVIEW.md, SERVICES.md
• All existing tests in all modules still pass