Federico Mariani created CAMEL-23395:
----------------------------------------
Summary: camel-openai: Add agentic loop trace property, cumulative
headers, and lifecycle events
Key: CAMEL-23395
URL: https://issues.apache.org/jira/browse/CAMEL-23395
Project: Camel
Issue Type: Improvement
Components: camel-openai
Reporter: Federico Mariani
Complements [CAMEL-23369|https://issues.apache.org/jira/browse/CAMEL-23369]
(OpenTelemetry GenAI observability)
The _camel-openai_ agentic loop currently uses only SLF4J logging for
observability. There is no structured way for downstream routes to inspect what
happened during an agentic execution, which tools were called, what they
returned, how many tokens each iteration consumed, or why the loop terminated.
Some headers are already set (`CamelOpenAIToolIterations`,
`CamelOpenAIMcpToolCalls`), but they only capture the final state, not the
per-iteration breakdown.
[CAMEL-23369|https://issues.apache.org/jira/browse/CAMEL-23369] addresses the
external observability layer (OpenTelemetry GenAI spans and metrics for all
camel-ai components). This issue focuses on the *internal agentic-loop-specific
state* that CAMEL-23369 would consume but that needs to exist first:
1. *Cumulative agentic token headers* — set `CamelOpenAIAgenticTotalTokens`,
`CamelOpenAIAgenticPromptTokens`, `CamelOpenAIAgenticCompletionTokens` with the
sum across all iterations. The existing `CamelOpenAIPromptTokens` /
`CamelOpenAICompletionTokens` headers only reflect the final model call.
Downstream routes need the cumulative total for cost tracking and routing
decisions.
2. *Per-iteration trace property* — store a `List<AgenticIterationTrace>` in
the exchange property `CamelOpenAIAgenticTrace`. Each entry captures:
- Iteration number
- Tool calls made (name + arguments summary)
- Tool results (truncated)
- Token usage for that iteration
- Duration
This gives users full visibility for debugging, auditing, and in-route decision
making. Unlike OTel spans, this property is available to downstream processors
in the same route.
3. EVALUATE THE OVERHEAD FIRST: *Camel EventNotifier lifecycle events* — emit
`ExchangeEvent` subtypes for agentic lifecycle points:
- `AgenticLoopStarted` (with tool count, max iterations)
- `AgenticToolCallExecuted` (with tool name, duration, success/failure)
- `AgenticLoopCompleted` (with iteration count, total tokens, stop reason)
These events are the natural integration point for CAMEL-23369: the OTel
instrumentation layer can listen for these events and map them to GenAI
semantic convention spans and metrics, rather than each AI component
duplicating instrumentation logic.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
