feat: Phase 4 — BOM and Integration (akces-agentic module)#297
Conversation
…EventCatalogProcessor for AgenticAggregateInfo, add documentation Agent-Logs-Url: https://github.com/elasticsoftwarefoundation/akces-framework/sessions/17cce424-6599-41b4-b234-27b320166042 Co-authored-by: jwijgerd <914840+jwijgerd@users.noreply.github.com>
…ntCatalogProcessor Agent-Logs-Url: https://github.com/elasticsoftwarefoundation/akces-framework/sessions/17cce424-6599-41b4-b234-27b320166042 Co-authored-by: jwijgerd <914840+jwijgerd@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Integrates the new akces-agentic module into the framework’s build/documentation ecosystem and extends the akces-eventcatalog annotation processor to generate EventCatalog service docs for @AgenticAggregateInfo-annotated aggregates.
Changes:
- Add
akces-agenticto the framework BOM for dependency management. - Extend the EventCatalog annotation processor + templates to emit “Singleton”-typed service pages for agentic aggregates (including built-in memory messages).
- Add/expand top-level docs (
FRAMEWORK_OVERVIEW.md,SERVICES.md) and updateREADME.mdto include AgenticAggregates.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| SERVICES.md | New Kubernetes CRD reference including AgenticAggregate and sidecar examples. |
| README.md | Adds AgenticAggregates to core concepts and lists the agentic module. |
| main/eventcatalog/src/test/java/.../EventCatalogProcessorTest.java | Adds a processor test for @AgenticAggregateInfo service doc generation. |
| main/eventcatalog/src/main/java/.../ServiceTemplateGenerator.java | Adds optional type frontmatter support for service docs. |
| main/eventcatalog/src/main/java/.../EventCatalogProcessor.java | Adds @AgenticAggregateInfo support and generates agentic aggregate service docs. |
| FRAMEWORK_OVERVIEW.md | New architecture overview with an AgenticAggregates section and comparisons. |
| bom/pom.xml | Adds akces-agentic as a managed dependency. |
| Stream.concat( | ||
| builtInReceives.stream(), | ||
| agenticHandledCommands.getOrDefault(agenticInfo, Collections.emptySet()).stream() | ||
| .map(typeElement -> typeElement.getAnnotation(CommandInfo.class)) | ||
| .filter(Objects::nonNull) | ||
| .map(annotation -> new ServiceTemplateGenerator.Message( | ||
| annotation.type(), | ||
| annotation.version() + ".0.0")) | ||
| ).toList(), |
There was a problem hiding this comment.
agenticHandledCommands / agenticProducedEvents are referenced when generating AgenticAggregate service docs, but these maps are never populated (handler matching + relationship building only populates the non-agentic aggregate maps). As a result, agentic service docs will always list only the built-in memory messages and omit any custom commands/events declared by the agentic aggregate. Extend the handler matching and relationship-building pipeline to also collect handled commands/events (and produced/error events) for agentic aggregates, or remove these fields if intentionally unsupported.
| @AgenticAggregateInfo( | ||
| value = "Assistant", | ||
| stateClass = AssistantState.class, | ||
| description = "AI Assistant AgenticAggregate", | ||
| maxMemories = 50) | ||
| @SuppressWarnings("unused") | ||
| public final class Assistant implements AgenticAggregate<AssistantState> { |
There was a problem hiding this comment.
This new test only validates that the built-in memory messages and type: Singleton appear in the generated service doc; it doesn’t exercise the newly added (but currently non-functional) path for including an agentic aggregate’s own handled commands/events or produced events. Add a test case where the agentic aggregate contains at least one @CommandHandler with produces (and corresponding @CommandInfo / @DomainEventInfo types) and assert those IDs appear in the generated MDX so regressions are caught.
| | External events | Via `@EventBridgeHandler` | Listens to **all** partitions directly | | ||
| | GDPR/PII | Supported | Not supported (agent memory is not PII) | | ||
| | Annotation | `@AggregateInfo` | `@AgenticAggregateInfo` | | ||
| | Kubernetes CRD | `AggregateService` | `AgenticAggregate` (short name `aag`) | |
There was a problem hiding this comment.
The CRD kind for standard aggregates is Aggregate (short name agg), not AggregateService (see operator CRD annotations and generated CRD YAML). Update this row to avoid misleading deployment/docs references.
| | Kubernetes CRD | `AggregateService` | `AgenticAggregate` (short name `aag`) | | |
| | Kubernetes CRD | `Aggregate` (short name `agg`) | `AgenticAggregate` (short name `aag`) | |
Integrates the
akces-agenticmodule into the build system, BOM, and documentation tooling. Extends the EventCatalog annotation processor to generate documentation for@AgenticAggregateInfo-annotated aggregates.BOM
akces-agentictobom/pom.xmlmanaged dependencies (main/pom.xmlalready included the module from Phase 2/3)EventCatalog Annotation Processor
@AgenticAggregateInfoto@SupportedAnnotationTypesand a dedicated processing pipeline (agenticAggregateCache,processAgenticAggregateInfoAnnotations())generateCatalogEntries()emits service docs for agentic aggregates withtype: Singletonin the MDX frontmatter and pre-populates built-in memory commands/events (StoreMemory,ForgetMemory,MemoryStored,MemoryRevoked)ServiceTemplateGenerator.ServiceMetadatagains an optionaltypefield; a 9-arg convenience constructor keeps all existing call sites unchangedGenerated service index for an agentic aggregate:
Documentation
README.md: AddedAgenticAggregatesto Core Concepts; addedagenticmodule to Architecture section with links to new docsFRAMEWORK_OVERVIEW.md(new): Full architecture reference — module table, all core concepts, and a dedicated AgenticAggregates section (comparison table vs regular aggregates, annotation, state interface contract, built-in commands/events, sliding-window eviction, external event subscription behaviour)SERVICES.md(new): Kubernetes CRD reference for all four service types (Aggregate,CommandService,QueryService,AgenticAggregate), includingAgenticAggregateSpecandSidecarSpecfield tables and a worked example deploying anAgenticAggregatewith a GitHub MCP Server sidecar