[jira] [Work started] (CAMEL-25408) camel-api - AI events: a common AiEvent API and an AI event type in core instead of component-specific Custom events

["Andrea Cosentino (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/CAMEL-25408?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Work on CAMEL-25408 started by Andrea Cosentino.
------------------------------------------------
> camel-api - AI events: a common AiEvent API and an AI event type in core instead of component-specific Custom events
> --------------------------------------------------------------------------------------------------------------------
>
>                 Key: CAMEL-25408
>                 URL: https://issues.apache.org/jira/browse/CAMEL-25408
>             Project: Camel
>          Issue Type: Improvement
>          Components: camel-ai, camel-core-api, camel-openai
>            Reporter: Claus Ibsen
>            Assignee: Andrea Cosentino
>            Priority: Major
>             Fix For: 4.24.0
>
>
> h3. Problem
> AI components fire their own {{CamelEvent}} classes, each with {{CamelEvent.Type.Custom}}:
> * camel-openai: {{OpenAIAgenticLoopStartedEvent}}, {{OpenAIAgenticLoopCompletedEvent}}, {{OpenAIAgenticToolCallExecutedEvent}} (on a package-private {{AbstractOpenAIExchangeEvent}})
> * camel-ai-tool: {{AiToolAuthorizationDeniedEvent}} (CAMEL-25404, PR #27480)
> Because each event is component-specific and only typed {{Custom}}, it is hard to track them for GenAI observability, and for anyone else:
> * an {{EventNotifier}} has to depend on every AI component and {{instanceof}} each event class to recognise them; {{Type.Custom}} says nothing about what the event is (camel-ai-observability, micrometer, dev console, TUI, management all have the same problem)
> * none of them implements {{CamelEvent.ExchangeEvent}} although they all carry the exchange ({{getExchange()}}), so notifiers that correlate by exchange / route skip them
> * GenAI observability (spans/metrics) went shared on purpose ({{camel-ai-observability-api}}, wired the same way in openai, langchain4j and spring-ai); the events are drifting the other way, one design per component
> h3. Proposal
> core/camel-api already has the {{org.apache.camel.ai}} package (@since 4.21, so far only {{CamelLangchain4jAttributes}}). Add the AI event API there, so every AI component fires events from one contract and anyone can observe them with no dependency on an AI component:
> * a new {{CamelEvent.Type}} value for AI events (for example {{Ai}}), used instead of {{Custom}}
> * {{AiEvent extends CamelEvent.ExchangeEvent}}: the common contract (for example the component / provider and the tool or model name)
> * sub-interfaces for what exists today: tool call denied (also a {{CamelEvent.FailureEvent}} with the {{CamelAuthorizationException}}), tool call executed, agent loop started, agent loop completed
> * {{@since 4.23}} on all new types and the new {{Type}} value
> Then:
> * move the camel-openai agentic events and the camel-ai-tool {{AiToolAuthorizationDeniedEvent}} onto these interfaces and the new type, before 4.23.0 is released, so the component-specific Custom events never ship in a release
> * the event classes can stay in the components (implementing the core interfaces), or share a small base in camel-support
> * camel-ai-observability can then turn any {{AiEvent}} into metrics / spans with one EventNotifier
> Things to check:
> * code that switches on {{CamelEvent.Type}} (for example {{ManagedEventNotifier}} special-cases {{Custom}}) should handle the new value
> * whether {{EventNotifier}} / {{EventNotifierSupport}} should get an {{ignoreAiEvents}} option like the other event categories, and how it relates to {{ignoreExchangeEvents}} since an {{AiEvent}} is also an {{ExchangeEvent}}
> * the docs of camel-openai and camel-ai-tool that document the current event classes
> _Created by Claude Code on behalf of davsclaus_



--
This message was sent by Atlassian Jira
(v8.20.10#820010)