CAMEL-23951: Expose agent Result sources and tool executions as headers

[atiaomar1978-hub]

Branch: CAMEL-23951-agent-sources-tool-headers
Commit: f09c3fd4dc17
PR link: https://github.com/atiaomar1978-hub/camel/pull/new/CAMEL-23951-agent-sources-tool-headers

---

Summary (for PR description)

CAMEL-23951: Expose agent Result.sources() and Result.toolExecutions() as message headers

The langchain4j-agent producer already mapped Result.content(), finish reason, and token usage to exchange headers (CAMEL-23860). RAG sources and tool execution details from the LangChain4j Result were dropped, which limited observability, auditing, and downstream routing.

This change adds two new output headers, following the same null/empty guard pattern as the existing metadata headers:

Header	Type	When set
CamelLangChain4jAgentSources	List<dev.langchain4j.rag.content.Content>	RAG retrieval populated Result.sources()
CamelLangChain4jAgentToolExecutions	List<dev.langchain4j.service.tool.ToolExecution>	Tools were invoked during the agent call

Native LangChain4j objects are stored on the exchange (same approach as FinishReason and chat’s RAG input header), not JSON-serialized strings.

Changes

• Headers.java — new SOURCES and TOOL_EXECUTIONS constants with @Metadata
• LangChain4jAgentProducer.java — populateTokenUsageHeaders renamed to populateResultHeaders; sources and tool executions populated when present
• LangChain4jAgentResultHeadersTest.java — 5 unit tests covering full metadata, empty lists, absent fields, sources-only, and tools-only
• Generated metadata — component JSON, catalog JSON, endpoint DSL header accessors
• Upgrade guide — note added under camel-langchain4j-agent in camel-4x-upgrade-guide-4_22.adoc

Test plan

• LangChain4jAgentResultHeadersTest — 5/5 passed
• Full camel-langchain4j-agent module tests in CI

[gnodet]

Clean, well-structured change that completes the agent Result metadata exposure started in CAMEL-23860.

What's good:

• Follows the established pattern: The null/empty guards (result.sources() != null && !result.sources().isEmpty()) are exactly consistent with the existing finishReason and tokenUsage guards — no surprises for anyone who's read this code before.
• Good method rename: populateTokenUsageHeaders → populateResultHeaders correctly reflects the broader scope now that it handles finish reason, token usage, sources, and tool executions.
• Proper @Metadata annotations: Both constants include javaType with the full generic signature (java.util.List<dev.langchain4j.rag.content.Content>) — this drives correct catalog and endpoint DSL generation.
• Native objects, not serialized strings: Storing Content and ToolExecution directly on headers (same approach as FinishReason) lets downstream processors inspect the rich object model without parsing.
• Thorough test coverage: 5 test cases cover the full matrix — all present, both empty, both absent, sources-only, tools-only. The assertSame checks confirm objects are passed through directly, not defensively copied (correct for immutable LangChain4j types).
• Upgrade guide: Concise note in the right section.

No issues found. LGTM.

Claude Code on behalf of gnodet — AI-generated review

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[davsclaus]

There are uncommitted changes
HEAD detached at pull/24917/merge
Changes not staged for commit:
(use "git add ..." to update what will be committed)
(use "git restore ..." to discard changes in working directory)
modified: dsl/camel-endpointdsl/src/generated/java/org/apache/camel/builder/endpoint/dsl/LangChain4jAgentEndpointBuilderFactory.java

[atiaomar1978-hub]

@davsclaus I will fix. and will resolve conflicts.

[gnodet]

Commit 29f3dd624bd8 — regenerated endpoint DSL Javadoc formatting (line wrapping). No behavioral change; prior review still applies.

Claude Code on behalf of gnodet — AI-generated review

[atiaomar1978-hub]

@davsclaus conflicts have been resolved , Please run the CI build and tests when you have chance.

[github-actions]

🧪 CI tested the following changed modules:

• catalog/camel-catalog
• components/camel-ai/camel-langchain4j-agent-api
• components/camel-ai/camel-langchain4j-agent
• docs
• dsl/camel-endpointdsl

---

🔬 Scalpel shadow comparison — Scalpel: 13 tested, 26 compile-only — current: 10 all tested

Maveniverse Scalpel detected 39 affected modules (current approach: 10).

⚠️ Modules only in Scalpel (29)

• apache-camel
• camel-allcomponents
• camel-catalog
• camel-catalog-console
• camel-catalog-lucene
• camel-catalog-maven
• camel-catalog-suggest
• camel-componentdsl
• camel-csimple-maven-plugin
• camel-endpointdsl
• camel-endpointdsl-support
• camel-itest
• camel-jbang-core
• camel-jbang-it
• camel-jbang-main
• camel-jbang-plugin-edit
• camel-jbang-plugin-generate
• camel-jbang-plugin-kubernetes
• camel-jbang-plugin-test
• camel-kamelet-main
• camel-launcher
• camel-report-maven-plugin
• camel-route-parser
• camel-yaml-dsl
• camel-yaml-dsl-deserializers
• camel-yaml-dsl-maven-plugin
• coverage
• docs
• dummy-component

Skip-tests mode would test 13 modules (5 direct + 8 downstream), skip tests for 26 (generated code, meta-modules)

Modules Scalpel would test (13)

• camel-catalog
• camel-endpointdsl
• camel-jbang-mcp
• camel-jbang-plugin-mcp
• camel-jbang-plugin-route-parser
• camel-jbang-plugin-tui
• camel-jbang-plugin-validate
• camel-langchain4j-agent
• camel-langchain4j-agent-api
• camel-launcher-container
• camel-yaml-dsl-validator
• camel-yaml-dsl-validator-maven-plugin
• docs

Modules with tests skipped (26)

• apache-camel
• camel-allcomponents
• camel-catalog-console
• camel-catalog-lucene
• camel-catalog-maven
• camel-catalog-suggest
• camel-componentdsl
• camel-csimple-maven-plugin
• camel-endpointdsl-support
• camel-itest
• camel-jbang-core
• camel-jbang-it
• camel-jbang-main
• camel-jbang-plugin-edit
• camel-jbang-plugin-generate
• camel-jbang-plugin-kubernetes
• camel-jbang-plugin-test
• camel-kamelet-main
• camel-launcher
• camel-report-maven-plugin
• camel-route-parser
• camel-yaml-dsl
• camel-yaml-dsl-deserializers
• camel-yaml-dsl-maven-plugin
• coverage
• dummy-component

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

⚠️ Some tests are disabled on GitHub Actions (@DisabledIfSystemProperty(named = "ci.env.name")) and require manual verification:

• components/camel-ai/camel-langchain4j-agent: 16 test(s) disabled on GitHub Actions

All tested modules (39 modules)

• Camel :: AI :: LangChain4j :: Agent
• Camel :: AI :: LangChain4j :: Agent :: API
• Camel :: All Components Sync point
• Camel :: Assembly
• Camel :: Catalog :: CSimple Maven Plugin (deprecated)
• Camel :: Catalog :: Camel Catalog
• Camel :: Catalog :: Camel Report Maven Plugin
• Camel :: Catalog :: Camel Route Parser
• Camel :: Catalog :: Console
• Camel :: Catalog :: Dummy Component
• Camel :: Catalog :: Lucene (deprecated)
• Camel :: Catalog :: Maven
• Camel :: Catalog :: Suggest
• Camel :: Component DSL
• Camel :: Coverage
• Camel :: Docs
• Camel :: Endpoint DSL
• Camel :: Endpoint DSL :: Support
• Camel :: Integration Tests
• Camel :: JBang :: Core
• Camel :: JBang :: Integration tests
• Camel :: JBang :: MCP
• Camel :: JBang :: Main
• Camel :: JBang :: Plugin :: Edit
• Camel :: JBang :: Plugin :: Generate
• Camel :: JBang :: Plugin :: Kubernetes
• Camel :: JBang :: Plugin :: MCP
• Camel :: JBang :: Plugin :: Route Parser
• Camel :: JBang :: Plugin :: TUI
• Camel :: JBang :: Plugin :: Testing
• Camel :: JBang :: Plugin :: Validate
• Camel :: Kamelet Main
• Camel :: Launcher
• Camel :: Launcher :: Container
• Camel :: YAML DSL
• Camel :: YAML DSL :: Deserializers
• Camel :: YAML DSL :: Maven Plugins
• Camel :: YAML DSL :: Validator
• Camel :: YAML DSL :: Validator Maven Plugin

---

⚙️ View full build and test results

[atiaomar1978-hub]

@davsclaus Please re-run the CI/build and tests again. I have merged main into this branch.