CAMEL-24614: camel-langchain4j-agent - clear error when no agent can be resolved (validated at process time)

[oscerd]

Issue

CAMEL-24614

Problem

LangChain4jAgentProducer resolves the agent from the registry with
lookupByNameAndType(agentId, Agent.class), which returns null when no matching bean exists. With no
agent/agentConfiguration/agentFactory configured and no registry bean named agentId, agent
stays null and process() fails with an opaque NullPointerException at agent.chat(...) instead of
a clear configuration error.

Fix

Resolve the agent and report the error in process() rather than at doStart(). When no
agent/agentFactory is set, re-resolve from the endpoint configuration
(endpoint.getConfiguration().getAgent()) and, only if that still yields nothing, throw a clear
IllegalArgumentException naming the endpoint and the configuration options.

Doing this at process time (instead of failing fast in doStart()) preserves the supported pattern of
configuring an agent on the endpoint after the route has started — used by dynamic wiring and by
several existing tests that call endpoint.getConfiguration().setAgent(...) post-start. Failing fast in
doStart() broke those flows (e.g. LangChain4jAgentMcpToolProviderFilterTest).

Testing

• New LangChain4jAgentMissingAgentTest sends an exchange through a route whose endpoint has an
  unresolvable agent and asserts the clear IllegalArgumentException ("No agent could be resolved")
  surfaces on the exchange.
• Full camel-langchain4j-agent unit suite green (includes the late-configuration tests).
• mvn -Psourcecheck validate green.

🤖 Generated with Claude Code

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

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

---

🔬 Scalpel shadow comparison — Scalpel: 9 tested, 27 compile-only — current: 9 all tested

Maveniverse Scalpel detected 36 affected modules (current approach: 9).

⚠️ 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 9 modules (1 direct + 8 downstream), skip tests for 27 (generated code, meta-modules)

Modules Scalpel would test (9)

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

Modules with tests skipped (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

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

• Camel :: AI :: LangChain4j :: Agent
• 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

[oscerd]

Heads-up on the latest push: the approach changed in response to CI. The original commit failed fast in doStart(), but that broke the supported late-configuration pattern (LangChain4jAgentMcpToolProviderFilterTest and others set endpoint.getConfiguration().setAgent(...) after the route starts). The validation now happens in process() and re-resolves from the endpoint configuration before raising the clear IllegalArgumentException, so late configuration keeps working. The full camel-langchain4j-agent unit suite is green. Re-requesting a quick look since the fix location moved.

Claude Code on behalf of oscerd

[gnodet]

Solid fix. The process()-time validation correctly preserves the supported late-configuration pattern while giving a clear IllegalArgumentException instead of an opaque NPE.

The test covers the happy path for the error message. All ast-grep findings on this file (broad-exception-catch at lines 199, 459, 536, 575, 691) are pre-existing and not introduced by this PR.

No issues found.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

[gnodet]

🔄 Backport Bot

Port PRs created:

• ✅ camel-4.22.x → [backport camel-4.22.x] CAMEL-24614: camel-langchain4j-agent - fail fast when no agent can be resolved #26118
• ✅ camel-4.18.x → [backport camel-4.18.x] CAMEL-24614: camel-langchain4j-agent - fail fast when no agent can be resolved #26119

ℹ️ If you push additional commits after /port, use /port again to update the port PRs.