oscerd opened a new pull request, #27714: URL: https://github.com/apache/camel/pull/27714
CAMEL-25408: AI events — a common `AiEvent` API and an `Ai` event type in core, instead of component-specific `Custom` events. ## Problem AI components fire their own `CamelEvent` classes, each typed `CamelEvent.Type.Custom`: - `camel-openai`: `OpenAIAgenticLoopStartedEvent`, `OpenAIAgenticLoopCompletedEvent`, `OpenAIAgenticToolCallExecutedEvent` - `camel-ai-tool`: `AiToolAuthorizationDeniedEvent` (CAMEL-25404) Because each is component-specific and only typed `Custom`, an `EventNotifier` (micrometer, dev console, management, a GenAI-observability backend) has to depend on every AI component and `instanceof` each class to recognise them, and `Type.Custom` says nothing about what the event is. None of them implemented `ExchangeEvent` either, although they all carry the exchange. GenAI observability (spans/metrics) already went shared on purpose (`camel-ai-observability-api`); the events were drifting the other way. ## What this does Adds the AI event contract to the existing `org.apache.camel.ai` package in `core/camel-api`, and moves the component events onto it — **before the events ship in any release** (they are not in the `camel-4.23.0` tag), so the component-specific `Custom` events never reach a release. **core/camel-api** (`@since 4.23`): - a new `CamelEvent.Type.Ai` value; - `AiEvent extends CamelEvent.ExchangeEvent` — the shared contract: `getProvider()` (a low-cardinality label such as `openai` / `ai-tool`), the exchange (for correlation), and `getType()` defaulted to `Ai`; - nested sub-interfaces for what exists today: `ToolCallDeniedEvent` (also a `FailureEvent`, carrying the `CamelAuthorizationException`), `ToolCallExecutedEvent`, `AgentLoopStartedEvent`, `AgentLoopCompletedEvent`. **camel-openai / camel-ai-tool**: the event classes stay in the components but now implement these interfaces and are `Type.Ai`; `getProvider()` returns `openai` / `ai-tool`. (`OpenAIAgenticToolCallExecutedEvent.getDurationMs()` → `getDurationMillis()` to match the interface — it had not shipped.) **core/camel-management**: `ManagedEventNotifier` skips `Type.Ai` when building MBean notification infos, as it already does for `Custom` (AI events are concrete classes with their own notification names). A listener can now do `event instanceof AiEvent` (or switch on `Type.Ai`) and read `getProvider()` / the sub-interface with no dependency on an AI component — which is what lets `camel-ai-observability` turn any `AiEvent` into metrics/spans with a single `EventNotifier` (a follow-up this enables). ## Design notes - **No `ignoreAiEvents` flag** (an open question in the issue): these events are fired through `ManagementStrategy.notify()`, which delivers to every notifier and does **not** consult the `EventNotifier` ignore flags (those are applied on the `EventHelper` lifecycle-event path). A notifier that wants to drop AI events filters them in its own `isEnabled`/`notify`, so the flag would have no effect on the firing path and is not added. `AiEvent` is an `ExchangeEvent`, so it is still correlatable by exchange. - `camel-event`'s `CamelEvent.Type` switch has a `default`, so the new value is handled there without change. ## Tests & docs - Updated the existing event tests (`OpenAIAgenticEventNotifierTest`, `OpenAIResponsesAgenticTest`, `AiToolAuthorizationDeniedEventTest`) to recognise the events as `Type.Ai`; they assert the same behaviour through the new contract. - `ai-tool-component.adoc` (Observing denials) and `openai-mcp.adoc` now describe the events as `AiEvent`s and match on the shared interface; catalog mirrors regenerated. - No upgrade-guide entry: the component-specific `Custom` events never shipped (not in the `camel-4.23.0` tag), so there is nothing to migrate. `main` only. --- _Claude Code on behalf of oscerd_ 🤖 Generated with [Claude Code](https://claude.com/claude-code) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
