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
I'll start by exploring the repository structure and finding code related to AiService, ReturnBehavior, and IMMEDIATE tool execution.
- Assistant
Let me examine the ReturnBehavior enum and the core AiService/ToolService handling of IMMEDIATE results.
- Assistant
Next I'll inspect how ToolService and DefaultAiServices enforce Result return types and how existing IMMEDIATE tests are structured.
- Assistant
I'll read the immediate-return path in DefaultAiServices and the existing IMMEDIATE tool tests.
- Assistant
I'll check the Quarkus PR reference, AiServiceStreamingResponseHandler, and tests that cover non-Result + IMMEDIATE cases.
- Assistant
I'll inspect tool execution result types and the streaming immediate-return path next.
- Assistant
I'll search for type-resolution helpers and any prior work or PR notes on non-Result IMMEDIATE returns.
- Assistant
Checking how
isReturnTypeResultis used and scanning for validation around IMMEDIATE return types. - Assistant
Checking void-return handling and looking for similar resolution logic elsewhere in the codebase.
- Assistant
I'll inspect DefaultToolExecutor for void/null tool results and review DefaultAiServices imports/structure for where to add resolution.
- Assistant
Let me look at the DefaultToolExecutor execute method more carefully for void returns, and also read lines around 157-195.
- Assistant
Checking for tests that expect IllegalConfigurationException when IMMEDIATE is used without Result.
- Assistant
Checking for existing primitive-boxing utilities in the codebase.
- Assistant
Implementing the feature: updating ToolService to allow non-Result returns (with TO_LLM guards), then resolving the immediate result in DefaultAiServices.
- Assistant
Editing the immediate-return branch in ToolService.
- Assistant
Now replace the shouldReturnImmediately block.
- Assistant
Need to navigate to the line first.
- Assistant
Now I can replace since I'm at the right location.
- Assistant
I'll add a helper on ToolService to resolve the immediate return value from tool executions.
- Assistant
Updating DefaultAiServices to resolve non-Result immediate tool returns.
- Assistant
Switching to DefaultAiServices for the immediate-return handling changes.
- Assistant
I'll update the immediateToolReturn handling and add the import.
- Assistant
Need to go to line 55 first
- Assistant
Let me do the import replace and the method body replace.
- Assistant
Now update the immediate return handling block.
- Assistant
Now replace the immediate return block.
- Assistant
Updating ReturnBehavior Javadoc and the tools tutorial docs to reflect non-Result support.
- Assistant
Update the javadocs for ReturnBehavior.
- Assistant
Also update IMMEDIATE and IMMEDIATE_IF_LAST enum constant docs.
- Assistant
Update IMMEDIATE_IF_LAST too.
- Assistant
Fixing the Javadoc typo:
{\code TO_LLM}→{@code TO_LLM}. - Assistant
Updating the tools tutorial documentation next.
- Assistant
I'll update the note section and add an example for non-Result return types.
- Assistant
I'll update the IMMEDIATE_IF_LAST doc note that still claims Result-only support.
- Assistant
Need to update that line.
- Assistant
Replace lineetable 1522
- Assistant
Cleaning up
resolveImmediateToolReturnto useTypeUtils.getRawClass, then writing a temporary verification test. - Assistant
Need to navigate first
- Assistant
Let me replace imports and the method body.
- Assistant
Now update the resolve method to use Type and TypeUtils.
- Assistant
Update resolveImmediateToolReturn signature to use Type and TypeUtils.getRawClass
- Assistant
Writing a temporary verification test and running existing related unit tests.
- Assistant
I'll avoid adding permanent tests — writing a temporary test outside the repo and running it with Maven.
- Assistant
Compiling the affected modules and running the smoke test.
- Assistant
HOME isn't set in this environment — setting it and retrying the build.
- Assistant
Compilation succeeded. Running the smoke test next.
- Assistant
Need full classpath. Let me get it properly.
- Assistant
The classpath should prefer local
target/classes(with my changes) over the installed SNAPSHOT jar. - Assistant
The smoke test had the wrong package declaration; fixing and re-running it.
- Assistant
Parameter names are stripped without
-parameters; checking how other tests handle that. - Assistant
Adding
@Pparameter annotations so the smoke test works without-parameters. - Assistant
Need to import ToolService
- Assistant
Checking how
@Pdefines parameter names. - Assistant
Need
@P(name = "a"), not@P("a"). - Assistant
Fixing the smoke test: null
Stringtool results hit a pre-existing message-building issue, so I'll use a nullable non-String type instead. - Assistant
Smoke tests passed. Running existing ReturnBehavior and IMMEDIATE-related unit tests next.
- Assistant
Fixing a bug: multi-round tool loops can accumulate prior executions, so non-Result mapping must use only the current turn's tools.
- Assistant
I'll add the immediate turn's tool executions separately to ToolServiceResult, or add a field for immediate-return tools only. I think the cleanest approach is to extend ToolServiceResult with a new field like
immediateReturnValue(Object) andimmediateReturnType(Type), so we can resolve the value directly when we have the current turn's tools. - Assistant
Updating DefaultAiServices so non-Result mapping only uses the current hail turn’s tool executions.
- Assistant
I'll put the helper on ToolService itself next to resolveImmediateToolReturn.
- Assistant
Now add toolExecutionsForImmediateReturn to ToolService.
- Assistant
Wrong file open — switching back to ToolService.
- Assistant
Adding
toolExecutionsForImmediateReturnafterresolveImmediateToolReturn/box. - Assistant
Rebuilding and re-running tests after the multi-round fix.
- Assistant
Adding the multi-round case with a shell edit, then rerunning the unit tests.
- Assistant
Verifying the final diff and cleaning up residual files.
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 →