CAMEL-23928: Add tool-calling behavior tests and documentation for AgentConfiguration

[atiaomar1978-hub]

Summary

The core CAMEL-23928 API (first-class tool-calling options on AgentConfiguration and the withAiServicesCustomizer() escape hatch wired through AbstractAgent.configureBuilder()) is already on main since #24492. This PR completes the ticket by adding behavioral test coverage and component documentation so the feature is discoverable and verified end-to-end.

Changes

• Unit tests (AgentConfigurationToolCallingBehaviorTest): verify hallucinated tool name recovery, max tool round-trip enforcement, tool execution error handler + compensation, and customizer-driven beforeToolExecution wiring via AgentWithoutMemory.
• Integration tests (LangChain4jAgentAiServicesCustomizerTest): verify the same options through the langchain4j-agent component with agentConfiguration beans and Camel route tools.
• Documentation (langchain4j-agent-component.adoc): document first-class tool-calling methods and the AiServices customizer escape hatch for options like beforeToolExecution, afterToolExecution, and toolSearchStrategy.
• Catalog mirror regenerated for the updated component documentation.

Testing

mvn test -pl components/camel-ai/camel-langchain4j-agent-api,components/camel-ai/camel-langchain4j-agent -am \
  -Dtest=AgentConfigurationToolCallingBehaviorTest,LangChain4jAgentAiServicesCustomizerTest \
  -DfailIfNoTests=false -Ddevelocity.buildCache.local.enabled=false

All 6 new tests pass locally.

JIRA

https://issues.apache.org/jira/browse/CAMEL-23928

---

AI-generated PR description on behalf of atiaomar1978-hub

[atiaomar1978-hub]

Review follow-up (Bugbot + security review)

AI-generated comment on behalf of atiaomar1978-hub

Findings addressed in latest commits

1. Catalog mirror out of sync (Bugbot, medium) — Regenerated catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/langchain4j-agent-component.adoc via mvn -pl catalog/camel-catalog clean generate-resources so the new Tool-calling options / withAiServicesCustomizer documentation is mirrored for CI.

2. Brittle assertion (security review, low) — maxToolCallingRoundTripsIsEnforced now asserts exception type + partial message (tool calling round trips) instead of an exact LangChain4j error string.

Review notes (no code change required)

• Security: Customizer hook is route-author configuration only (registry/bean), not URI-exposed — no new untrusted trust-boundary path.
• Test flakiness: Tests use deterministic stub ChatModels; no Thread.sleep() or timing dependencies.
• Scope: Core CAMEL-23928 API landed in chore: reorganize bundled jbang examples with category sub-grouping #24492; this PR adds behavioral coverage + docs to close the ticket.

Tests run locally

mvn test -pl components/camel-ai/camel-langchain4j-agent-api,components/camel-ai/camel-langchain4j-agent -am \
  -Dtest=AgentConfigurationToolCallingBehaviorTest,LangChain4jAgentAiServicesCustomizerTest \
  -DfailIfNoTests=false -Ddevelocity.buildCache.local.enabled=false

All 6 new tests pass.

[davsclaus]

Reviewed against the project's rules and standards (test conventions, doc/catalog sync, commit format, JIRA ownership).

Verification performed:

• Checked out the branch and ran the two new test classes locally (CI has not triggered any runs on this branch yet): all 6 new tests pass.
• Confirmed formatter:validate / impsort:check pass on both touched modules.
• Confirmed every AgentConfiguration method referenced (withMaxToolCallingRoundTrips, withHallucinatedToolNameStrategy, withToolExecutionErrorHandler, withToolArgumentsErrorHandler, withCompensateOnToolErrors, withExecuteToolsConcurrently, withAiServicesCustomizer) already exists on main (landed via #24492), so this PR is purely additive coverage + docs as described.
• Confirmed the catalog mirror (catalog/camel-catalog/.../langchain4j-agent-component.adoc) is byte-identical to the source doc change.
• Tests use AssertJ assertions and no Thread.sleep(), consistent with this project's test conventions.
• No scope drift: only tests + docs are touched, matching the PR description.

One small documentation suggestion left as an inline comment — not blocking.

This review does not replace specialized review tools (CodeRabbit/Sourcery) or static analysis (SonarCloud).

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

[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.

[github-actions]

🧪 CI tested the following changed modules:

• catalog/camel-catalog
• components/camel-ai/camel-langchain4j-agent-api
• components/camel-ai/camel-langchain4j-agent

---

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

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

⚠️ Modules only in Scalpel (27)

• apache-camel
• camel-allcomponents
• camel-catalog
• camel-catalog-console
• camel-catalog-maven
• camel-catalog-suggest
• camel-componentdsl
• 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 11 modules (3 direct + 8 downstream), skip tests for 26 (generated code, meta-modules)

Modules Scalpel would test (11)

• camel-catalog
• 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

Modules with tests skipped (26)

• apache-camel
• camel-allcomponents
• camel-catalog-console
• camel-catalog-maven
• camel-catalog-suggest
• camel-componentdsl
• 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

ℹ️ 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 (37 modules)

• Camel :: AI :: LangChain4j :: Agent
• Camel :: AI :: LangChain4j :: Agent :: API
• Camel :: All Components Sync point
• Camel :: Assembly
• Camel :: Catalog :: Camel Catalog
• Camel :: Catalog :: Camel Report Maven Plugin
• Camel :: Catalog :: Camel Route Parser
• Camel :: Catalog :: Console
• Camel :: Catalog :: Dummy Component
• 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

[gnodet]

Clean, well-structured PR that adds meaningful behavioral test coverage and clear documentation for the CAMEL-23928 tool-calling options and AiServices customizer. Tests fill a real gap between existing getter/setter unit tests and URI parameter tests.

Highlights:

• Tests verify meaningful end-to-end behavior: hallucinated tool name recovery, max round-trip enforcement, error handler with compensation, and customizer-driven beforeToolExecution wiring.
• Documentation is well-organized with a quick-reference AsciiDoc table, realistic code examples, and accurate explanation of customizer ordering.
• Catalog mirror properly synchronized, no convention violations.

📋 PR Metadata

Aspect	Current	Suggested
Category	(unlabeled)	test
Milestone	(none)	4.23.0

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of Guillaume Nodet