[
https://issues.apache.org/jira/browse/CAMEL-23395?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-23395:
--------------------------------
Fix Version/s: 4.23.0
> 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
> Assignee: Omar Atie
> Priority: Minor
> Fix For: 4.23.0
>
>
> 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)
