Class DecisionAgentBuilder<T>

java.lang.Object
dev.langchain4j.agentic.agent.DecisionAgentBuilder<T>
Type Parameters:
T - the decision agent interface
@Experimental public class DecisionAgentBuilder<T> extends Object
Builds a decision agent: an agent of an agentic system whose implementation is a single call to a DecisionModel instead of a chat model. It is defined by a Decision Service interface (see DecisionServices) whose method also carries the @Agent annotation: 
public interface CategoryRouter {

    @Decide("Which kind of expert should handle this request?")
    @Agent(value = "Categorizes a user request", outputKey = "category")
    RequestCategory classify(@V("request") String request);
}

CategoryRouter router = AgenticServices.decisionAgentBuilder(CategoryRouter.class)
        .decisionModel(decisionModel)
        .build();
The arguments of the method are read from the AgenticScope by name, like for every agent, and sent to the decision model as the input of the decision (objects are converted to maps, as in Decision Services); the return type determines the questions: boolean, an enum, YesNoAnswer, Choice<enum>, Scale<enum>, an object whose fields are of those types, optionally wrapped in DecisionResult. The answer is written as it is to the output key, so that the activation conditions, the exit conditions and the agents that follow can read it, including its probabilities. CompletableFuture return types are not supported: use async(boolean) to run the agent asynchronously.

Each invocation makes one blocking call to the decision model. The response of the model, with the probabilities of its answers, its model name and its token usage, is reported to the AgentListeners through AgentResponse.decisionResponse() and recorded by the AgentMonitor. A decision agent has no chat memory, tools, retrieval or guardrails.

Since:
1.23.0

  • Constructor Details

  • Method Details

    • withoutDeclarativeConfiguration

      public static <T> DecisionAgentBuilder<T> withoutDeclarativeConfiguration(Class<T> agentServiceClass)

    • decisionModel

      public DecisionAgentBuilder<T> decisionModel(DecisionModel decisionModel)
      Sets the DecisionModel answering the question(s) of this agent.

    • decisionModelProvider

      public DecisionAgentBuilder<T> decisionModelProvider(Function<AgenticScope, DecisionModel> decisionModelProvider)
      Sets a provider that resolves the DecisionModel from the AgenticScope before each invocation, for example to pick a model depending on the state of the scope. Alternative to decisionModel(DecisionModel).

    • thresholdProvider

      public DecisionAgentBuilder<T> thresholdProvider(ThresholdProvider thresholdProvider)
      Sets the provider of the threshold of the boolean answers of this agent: the answer is true when the probability of "yes" is at least the threshold. The provider is called at every invocation, so the threshold can come from configuration that changes at runtime. Without it, and without threshold, the threshold is 0.5. Mutually exclusive with threshold(double). Like a fixed threshold, it is only allowed when the agent has a boolean answer, otherwise build() fails.

    • threshold

      public DecisionAgentBuilder<T> threshold(double threshold)
      Sets a fixed threshold for the boolean answers of this agent: the answer is true when the probability of "yes" is at least the threshold. Mutually exclusive with thresholdProvider(ThresholdProvider). Thresholds are specific to a decision model and to its version. A threshold is only allowed when the agent has a boolean answer, otherwise build() fails: a YesNoAnswer, a Choice or a Scale carries the probabilities to apply a threshold to.
      Parameters:
      threshold - a value between 0 and 1
      Throws:
      IllegalArgumentException - if the threshold is not between 0 and 1

    • requestParameters

      public DecisionAgentBuilder<T> requestParameters(DecisionRequestParameters requestParameters)
      Sets the parameters of every decision request of this agent, such as the model name, overriding the defaults of the decision model.

    • name

      public DecisionAgentBuilder<T> name(String name)
      Sets the name of this agent, overriding the one of @Agent or the method name.

    • description

      public DecisionAgentBuilder<T> description(String description)
      Sets the description of this agent, overriding the one of @Agent. It is what a supervisor reads to decide when to invoke this agent, so it should say which question the agent answers.

    • outputKey

      public DecisionAgentBuilder<T> outputKey(String outputKey)
      Sets the key of the AgenticScope where the answer of this agent is written, overriding the one of @Agent.

    • outputKey

      public DecisionAgentBuilder<T> outputKey(Class<? extends TypedKey<?>> outputKey)
      Sets the output key using a TypedKey class for type-safe scope access.

    • async

      public DecisionAgentBuilder<T> async(boolean async)
      Controls whether this agent executes asynchronously within an agentic system: the decision call then runs on the executor used for every asynchronous agent, and the agents reading its output wait for it.

    • optional

      public DecisionAgentBuilder<T> optional(boolean optional)
      Controls whether this agent is optional: when it is, it is skipped instead of failing when one of its arguments is missing from the AgenticScope.

    • activationCondition

      public DecisionAgentBuilder<T> activationCondition(Predicate<AgenticScope> activationCondition)
      Sets the condition under which this agent runs when it is invoked as a subagent of an agentic system. When the condition is false the agent is skipped, without writing anything to the AgenticScope. The condition is ignored when this agent is invoked directly. It can be evaluated more than once, so it must be free of side effects.

    • activationCondition

      public DecisionAgentBuilder<T> activationCondition(String description, Predicate<AgenticScope> activationCondition)
      Sets the condition under which this agent runs when it is invoked as a subagent of an agentic system, with a human-readable description used in logs, listeners and reports.
      See Also:

    • listener

      public DecisionAgentBuilder<T> listener(AgentListener agentListener)
      Adds a listener of the invocations of this agent, composed with the ones already registered.

    • agentInstanceFactory

      public DecisionAgentBuilder<T> agentInstanceFactory(Function<InternalAgent, Object> factory)

    • hasDecisionModel

      public boolean hasDecisionModel()
      Whether a decision model, or a provider of it, has been set.

    • build

      public T build()
      Builds the decision agent.
      Throws:
      IllegalArgumentException - if neither or both of the decision model and its provider are set, if both a threshold and a threshold provider are set, or if one of them is set on an agent without a boolean answer