ISSUE DESCRIPTION [FEATURE] support non Result return types for AiService when tool…
- User
ISSUE DESCRIPTION
[FEATURE] support non Result return types for AiService when tool execution is IMMEDIATE Is your feature request related to a problem? Please describe. If using ReturnBehavior.IMMEDIATE, your AiService method has to return Result even if all tools called return
voidor all returnnullor there's one tool method that returns same type as AiService return type.Describe the solution you'd like I'd like to support non-Result return types for AiService methods when tool execution has IMMEDIATE results based on these rules:
- If ai service method return type is void, just return null
- If any tool executions are TO_LLM throw exception (IMMEDIATE_IF_LAST case)
- If all tool executions have a null result and return type is nullable (not a primitive), then return null
- If there is one non-null tool execution result, and the result can be resolved to the return type, then return that object
I have a PR for this open in Quarkus too:
https://github.com/quarkiverse/quarkus-langchain4j/pull/2529
Interface
No new interfaces are introduced.
ADDITIONAL ADVICE
Since you are given a git repository, you can use git commands to simplify your work. For example, if you made a mistake and want to revert your changes, you can use
git checkout <file>to restore the file to its original state. You can also reset all changes in the repository usinggit reset --hardcommand. Additionally, you can usegit stashandgit stash popto temporarily save your changes and restore them later. Finally, you can see the changes that you've made (which will be submitted when you callsubmit) usinggit statusorgit diffcommands. However you don't need to usegit addorgit commitbefore submitting your changes. In fact,submitonly submits currently unstaged changes because it usesgit diffto get the changes that need to be submitted.CHECKLIST
Before submitting your solution, please go over the following checklist and make sure you've done everything:
- If an error was reported in the issue description, I have successfully reproduced it.
- If an error was reported in the issue description, I have confirmed that my fix resolves the error.
- I have thought about edge cases and made sure my fix handles them as well.
- I have run existing tests in the repository that might have been affected by the change I made and confirmed that they pass. I want you to list every bullet from this checklist and write your reasoning for why you think you did it or didn't need to.
Repository has been uploaded and your shell is currently at the repository root. Time to solve the issue!
(Current directory: /langchain4j, current file: none) bash-$
Assistant
Now let me make the edits to
ToolService.Assistant
Now add imports and the PRIMITIVE_TO_BOXED_TYPE map.
Assistant
Now add the PRIMITIVE_TO_BOXED_TYPE constant.
Assistant
Now update
ToolServiceResultto holdimmediateReturnValue.Assistant
Now update
DefaultAiServices.Assistant
Now let's compile.
Assistant
Now run the broader existing test suites in the langchain4j module related to services/tools.
Assistant
Reproduced the original failure. Now restore the fix and confirm it passes.
Assistant
Implementation complete. Summary of changes:
ToolService.executeInferenceAndToolsLoop(...): now takes the AI Service method'sType returnType(instead ofboolean isReturnTypeResult) and no longer unconditionally throws for non-Resultreturn types. It collects the current round'sToolExecutions and computes an immediate return value.- New
ToolService.immediateReturnValue(returnType, returnBehaviors, toolExecutions)implementing the requested rules in order:Result→null(unchanged behavior),void/Void→null, anyTO_LLMin the immediate round →IllegalConfigurationException, all tool resultsnull→null(or exception if the return type is primitive), exactly one non-null result assignable (with boxing) to the return type → that object, otherwiseIllegalConfigurationException. ToolServiceResult: newimmediateReturnValuefield/accessor/builder method (@Internalclass).DefaultAiServices: on an immediate tool return, returns theResultas before forResult<T>methods, otherwise returns the resolvedimmediateReturnValue(firing the completion event as usual).- Docs/Javadoc (
tools.md,ReturnBehavior) updated to describe the new supported return types and rules;langchain4j/revapi.jsongot a justified ignore for the internal signature change.
Checklist:
- "If an error was reported in the issue description, I have successfully reproduced it." — Done. I wrote a temporary test (
ReproTest) with an AI Service returningStringand anIMMEDIATEtool and ran it against the stashed (original) code: it failed withIllegalConfigurationException: AI Service method must return a dev.langchain4j.service.Result type to use tools with ReturnBehavior.IMMEDIATE/IMMEDIATE_IF_LAST. - "I have confirmed that my fix resolves the error." — Done. After restoring my changes the same test passes (returns
"immediate"), and a broader temporary test class (14 cases:String,void,Integer,int, POJO, multiple results,TO_LLMmix,Result<T>,IMMEDIATE_IF_LAST, no-immediate-return) all passed. Both temporary test files were deleted before submitting. - "I have thought about edge cases." — Covered:
void/Voidmethods, primitive return types with all-null tool results (exception) vs boxed types (null), primitive boxing for compatible results (int←Integer), multiple non-null results (exception), incompatible types (exception),TO_LLMmixed withIMMEDIATE_IF_LAST(exception, but only for the round that triggers immediate return, so multi-round flows still work),Result<T>behavior left untouched, streaming path unaffected,nullreturnType guarded. - "I have run existing tests that might have been affected." — Done. Full
langchain4jmodule test suite (1385 tests) andlangchain4j-corepass, includingReturnBehaviorCombinationsTest,ProgrammaticCreatedImmediateReturnToolTest,StreamingProgrammaticCreatedImmediateReturnToolTest,ToolServiceTest. I also verifiedmvn verify(revapi API check) passes for both modules; the existing IT assertionshould_throw_using_immediate_tool_on_service_not_returning_Resultstill matches because the new mismatch message contains bothIMMEDIATEand theResultclass name. No existing tests were modified.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.
Identical first prompt
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.5-35B-A3BCompare side by side →
Qwen/Qwen3.5-35B-A3BCompare side by side →