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, described by its name and description, 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 ("Should the agent '...' handle this request?"), 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.

  • 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, or if two subagents have the same name.

      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, 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, if the router agent is not a typed agent interface with at least one argument to send to the decision model, or if two subagents have the same name.

      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

    • 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)