[jira] [Commented] (CAMEL-23395) camel-openai: Add agentic loop trace property, cumulative headers, and lifecycle events

["Claus Ibsen (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/CAMEL-23395?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18112518#comment-18112518 ] 

Claus Ibsen commented on CAMEL-23395:
-------------------------------------

Merged via https://github.com/apache/camel/pull/26148 (commit 3d443a96cf081bd6865d1836c49c6f50f80ead4f).

_Claude Code on behalf of davsclaus_

> 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)