Enum Class ReturnBehavior

java.lang.Object

java.lang.Enum<ReturnBehavior>

dev.langchain4j.agent.tool.ReturnBehavior

All Implemented Interfaces:

Serializable, Comparable<ReturnBehavior>, Constable

@Experimental
public enum ReturnBehavior
extends Enum<ReturnBehavior>

Per-tool setting controlling what happens with a tool's result after execution.

In the default case (TO_LLM), every tool result is appended to the conversation and sent back to the LLM for further processing — AI Service execution loop runs another turn. With IMMEDIATE or IMMEDIATE_IF_LAST, certain tool-call patterns short-circuit the loop and return tool call result(s) directly to the caller inside the dev.langchain4j.service.Result.

Immediate-return rule applied after each LLM response: AI Service execution loop returns immediately iff

1. no tool in the response errored, AND
2. either the last tool is IMMEDIATE_IF_LAST, or every tool is IMMEDIATE/IMMEDIATE_IF_LAST (no TO_LLM mixed in).

Immediate return vs. reprocess for every order of behaviors (no errors), as exercised by ReturnBehaviorCombinationsTest:

  [TO_LLM]                                 -> reprocess
  [TO_LLM, TO_LLM]                         -> reprocess
  [IMMEDIATE]                              -> return immediately
  [IMMEDIATE, IMMEDIATE]                   -> return immediately
  [TO_LLM, IMMEDIATE]                      -> reprocess
  [IMMEDIATE, TO_LLM]                      -> reprocess
  [IMMEDIATE_IF_LAST]                      -> return immediately
  [IMMEDIATE_IF_LAST, IMMEDIATE_IF_LAST]   -> return immediately
  [TO_LLM, IMMEDIATE_IF_LAST]              -> return immediately
  [IMMEDIATE_IF_LAST, TO_LLM]              -> reprocess
  [IMMEDIATE, IMMEDIATE_IF_LAST]           -> return immediately
  [IMMEDIATE_IF_LAST, IMMEDIATE]           -> return immediately
  [TO_LLM, IMMEDIATE, IMMEDIATE_IF_LAST]   -> return immediately
  [TO_LLM, IMMEDIATE_IF_LAST, IMMEDIATE]   -> reprocess
  [IMMEDIATE, TO_LLM, IMMEDIATE_IF_LAST]   -> return immediately
  [IMMEDIATE, IMMEDIATE_IF_LAST, TO_LLM]   -> reprocess
  [IMMEDIATE_IF_LAST, TO_LLM, IMMEDIATE]   -> reprocess
  [IMMEDIATE_IF_LAST, IMMEDIATE, TO_LLM]   -> reprocess

Any tool error forces reprocess regardless of behaviors, so the LLM can react to the error on the next turn.

IMMEDIATE and IMMEDIATE_IF_LAST are only allowed on AI services declaring dev.langchain4j.service.Result as their return type. Using either on a service with a different return type causes an IllegalConfigurationException the first time an immediate return would occur.

Nested Class Summary

Nested classes/interfaces inherited from class Enum

Enum.EnumDesc<E>

Enum Constant Summary

Enum Constants

Enum Constant	Description
IMMEDIATE	Returns AI Service execution loop result(s) to the caller (inside the dev.langchain4j.service.Result) when every tool in the response is IMMEDIATE or IMMEDIATE_IF_LAST, and no tool errored.
IMMEDIATE_IF_LAST	Returns AI Service execution loop result(s) to the caller when this tool is positioned last in the LLM response.
TO_LLM	The tool result is sent back to the LLM for further processing — AI Service execution loop continues.

Method Summary

Modifier and Type	Method	Description
static ReturnBehavior	valueOf(String name)	Returns the enum constant of this class with the specified name.
static ReturnBehavior[]	values()	Returns an array containing the constants of this enum class, in the order they are declared.

Methods inherited from class Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

TO_LLM

public static final ReturnBehavior TO_LLM

The tool result is sent back to the LLM for further processing — AI Service execution loop continues. This is the default behavior.

IMMEDIATE

public static final ReturnBehavior IMMEDIATE

Returns AI Service execution loop result(s) to the caller (inside the dev.langchain4j.service.Result) when every tool in the response is IMMEDIATE or IMMEDIATE_IF_LAST, and no tool errored.

A single TO_LLM tool anywhere in the response prevents the immediate return and the loop runs another turn. Errors in any tool also prevent the immediate return so the LLM can react to the error.

Examples (full matrix in the class-level Javadoc):

  [IMMEDIATE]                              -> return immediately
  [IMMEDIATE, IMMEDIATE]                   -> return immediately
  [IMMEDIATE, IMMEDIATE_IF_LAST]           -> return immediately   (every tool is IMMEDIATE/IMMEDIATE_IF_LAST)
  [IMMEDIATE_IF_LAST, IMMEDIATE]           -> return immediately   (every tool is IMMEDIATE/IMMEDIATE_IF_LAST)
  [TO_LLM, IMMEDIATE]                      -> reprocess
  [IMMEDIATE, TO_LLM]                      -> reprocess

Only allowed on AI services returning dev.langchain4j.service.Result.

IMMEDIATE_IF_LAST

public static final ReturnBehavior IMMEDIATE_IF_LAST

Returns AI Service execution loop result(s) to the caller when this tool is positioned last in the LLM response. Intended for tools the LLM uses to explicitly close an action sequence — placing the tool last is the LLM's signal that no further LLM processing is needed.

Also counts toward the all-immediate rule of IMMEDIATE: a response made up only of IMMEDIATE and/or IMMEDIATE_IF_LAST tools returns immediately regardless of which one is last.

If positioned anywhere other than last, AND any other tool in the response is TO_LLM, the loop runs another turn — all tool call results (including this one) are sent to the LLM. Errors in any tool also prevent the immediate return so the LLM can react to the error.

Examples (full matrix in the class-level Javadoc):

  [IMMEDIATE_IF_LAST]                      -> return immediately
  [TO_LLM, IMMEDIATE_IF_LAST]              -> return immediately   (last is IMMEDIATE_IF_LAST)
  [IMMEDIATE_IF_LAST, IMMEDIATE_IF_LAST]   -> return immediately
  [IMMEDIATE_IF_LAST, IMMEDIATE]           -> return immediately   (every tool is IMMEDIATE/IMMEDIATE_IF_LAST)
  [IMMEDIATE_IF_LAST, TO_LLM]              -> reprocess  (not last; TO_LLM disqualifies all-immediate rule)
  [TO_LLM, IMMEDIATE_IF_LAST, IMMEDIATE]   -> reprocess  (not last; TO_LLM disqualifies all-immediate rule)

Only allowed on AI services returning dev.langchain4j.service.Result.

Method Details

values

public static ReturnBehavior[] values()

Returns an array containing the constants of this enum class, in the order they are declared.

Returns:

an array containing the constants of this enum class, in the order they are declared

valueOf

public static ReturnBehavior valueOf(String name)

Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum class has no constant with the specified name

NullPointerException - if the argument is null