Claus Ibsen created CAMEL-25408:
-----------------------------------
Summary: 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-core-api, camel-ai, camel-openai
Reporter: Claus Ibsen
Assignee: Andrea Cosentino
Fix For: 4.23.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)
