Class DecisionRouterPlanner

java.lang.Object
dev.langchain4j.agentic.patterns.decisionrouter.DecisionRouterPlanner
All Implemented Interfaces:
Planner
@Experimental public class DecisionRouterPlanner extends Object implements Planner
A router planner that lets a DecisionModel choose which subagents handle a request. The input of the decision is made of the arguments of the router agent itself, read from the AgenticScope.

Without an activation threshold, each subagent is an option of a single choice question, by default "Which agent is best suited to handle this request?", described by its description, or by its name when it has none, and the planner invokes only the most probable subagent and returns its output.

With an activation threshold, the planner asks instead one yes/no question per subagent, all in the same request (by default "Should the agent '...' (its description) handle this request?", where a subagent without a description is described by its name), invokes in parallel all the subagents whose probability of "yes" is at least the threshold, and returns a map from the name of each invoked subagent to its output, so the method of the router agent must return a Map, which is checked when the router is invoked. These probabilities are independent of each other: several subagents can reach a high threshold, adding a subagent does not change the probabilities of the others, and when no subagent reaches the threshold none is invoked and the result is an empty map.

The planner identifies a subagent by its name, which names its option or its question. Several subagents can have the same name: each of them is then identified by its id instead, the decision model tells them apart by their descriptions, and in the map returned with an activation threshold the output of each of them is under its id.

Only the subagents whose activation condition holds are offered to the decision model. When none does, the model isn't asked at all and the result is null, or an empty map with an activation threshold. Without an activation threshold, when only one does, it is invoked without asking the model.

A planner is created with one of the constructors, or through its builder, which also allows replacing the texts of both questions.

A planner instance holds the state of a single invocation and is not thread-safe, so the agentic system must be given a supplier creating a new instance at each invocation, for example () -> new DecisionRouterPlanner(decisionModel), while the decision model can be shared. An instance that is initialized a second time fails with an IllegalStateException.

  • Field Details

    • DEFAULT_CHOICE_QUESTION

      public static final String DEFAULT_CHOICE_QUESTION
      The default question asked to choose among the subagents, which are its options, when the router has no activation threshold.
      See Also:

    • DEFAULT_RELEVANCE_QUESTION_TEMPLATE

      public static final PromptTemplate DEFAULT_RELEVANCE_QUESTION_TEMPLATE
      The default template of the yes/no question asked for each subagent when the router has an activation threshold, with the variables {{name}} and {{description}} of the subagent.

  • Constructor Details

    • DecisionRouterPlanner

      public DecisionRouterPlanner(DecisionModel decisionModel)
      Creates a router invoking only the subagent that the decision model considers the most probable.

      When the router is invoked, before asking the decision model, it fails with an IllegalArgumentException if the router agent is not a typed agent interface with at least one argument to send to the decision model.

      Parameters:
      decisionModel - the decision model choosing the subagent to invoke
      Throws:
      IllegalArgumentException - if decisionModel is null

    • DecisionRouterPlanner

      public DecisionRouterPlanner(DecisionModel decisionModel, double activationThreshold)
      Creates a router asking the decision model, for each subagent, whether it should handle the request, and invoking in parallel all the subagents whose probability of "yes" is at least the given threshold.

      The result of the router is then a map from the name of each invoked subagent to its output, or from its id when several subagents have that name, so the method of the router agent must return a Map (or a ResultWithAgenticScope of a Map). When the router is invoked, before asking the decision model, it fails with an IllegalArgumentException if it does not, or if the router agent is not a typed agent interface with at least one argument to send to the decision model.

      Parameters:
      decisionModel - the decision model choosing the subagents to invoke
      activationThreshold - the minimum probability of "yes" for a subagent to be invoked, strictly between 0 and 1
      Throws:
      IllegalArgumentException - if decisionModel is null, or if activationThreshold is not strictly between 0 and 1

  • Method Details

    • builder

      public static DecisionRouterPlanner.Builder builder()

    • init

      public void init(InitPlanningContext initPlanningContext)
      Specified by:
      init in interface Planner

    • firstAction

      public Action firstAction(PlanningContext planningContext)
      Description copied from interface: Planner
      Returns the first action to execute when the planner starts (or resumes). Defaults to delegating to Planner.nextAction(PlanningContext).
      Specified by:
      firstAction in interface Planner
      Parameters:
      planningContext - the current planning context
      Returns:
      the first action to execute

    • nextAction

      public Action nextAction(PlanningContext planningContext)
      Description copied from interface: Planner
      Determines the next action to execute based on the result of the previous agent invocation.
      Specified by:
      nextAction in interface Planner
      Parameters:
      planningContext - the current planning context, including the previous agent's result
      Returns:
      the next action to execute

    • executionState

      public Map<String,Object> executionState()
      Description copied from interface: Planner
      Returns the planner's current execution state as a map of serializable values. This state is persisted to the AgenticScope after each agent invocation, enabling the planner to resume from the correct position after a crash.

      The returned state must be such that, when passed to Planner.restoreExecutionState(Map) and Planner.firstAction(PlanningContext) is called, the planner produces the correct resume action.

      Stateless planners (e.g., parallel, conditional) can use the default empty implementation.

      Specified by:
      executionState in interface Planner
      Returns:
      a map of state entries to persist, or an empty map if no state needs saving

    • restoreExecutionState

      public void restoreExecutionState(Map<String,Object> state)
      Description copied from interface: Planner
      Restores the planner's execution state from a previously saved map. Called by the execution loop before Planner.firstAction(PlanningContext) when recovering from a persisted scope.
      Specified by:
      restoreExecutionState in interface Planner
      Parameters:
      state - the previously saved execution state

    • topology

      public AgenticSystemTopology topology()
      Description copied from interface: Planner
      Returns the topology of the agentic system managed by this planner.
      Specified by:
      topology in interface Planner
      Returns:
      the topology (defaults to AgenticSystemTopology.SEQUENCE)