Class ConfidenceCascadePlanner

java.lang.Object
dev.langchain4j.agentic.patterns.cascade.ConfidenceCascadePlanner
All Implemented Interfaces:
Planner
@Experimental public class ConfidenceCascadePlanner extends Object implements Planner
A planner trying its subagents one at a time, from the cheapest to the most capable, until one of them gives an answer that a DecisionModel accepts. The subagents are the tiers of the cascade, in declaration order: for example an agent on a small model, the same agent on a large model, and finally a human.

After each tier answers, the planner asks the decision model the yes/no question "Does the answer fully and correctly address the request?", with an input made of the arguments of the cascade agent itself, read from the AgenticScope, plus the answer of the tier under the candidateAnswer field. If the probability of "yes" is at least the acceptance threshold the answer is returned as the result of the cascade, otherwise the next tier is tried. The last tier is never graded: its answer is returned anyway. More generally, the answer of a tier is returned without grading it when no later tier is active, according to the activation conditions of the subagents, and a tier that is skipped when invoked is passed over without a grade. When the remaining tiers are all skipped, the result is the latest answer obtained, or null if no tier answered.

An optional acceptance criterion describes when the answer should be accepted, for instance "The answer gives concrete steps and does not ask the user to contact support", and is sent to the decision model as the yesWhen description of the question. The arguments are sent as they are, so they can be strings, numbers, booleans, maps and lists of them, or Contents such as images, and an argument of any other type is rejected by the decision model with an error explaining which types are supported: the application decides what is sent to the provider of the decision model. The answer is sent as it is when it is such a value, and converted to maps and lists through a JSON round trip otherwise, so a tier can return a typed value.

The planner saves the tier it is trying as its execution state, so that after a suspension, for instance because a tier is waiting for a human, or after a crash, the cascade resumes from that tier and does not pay again for the cheaper ones. A crash during the grading call itself makes the tier being graded run again, because the state is saved only after the grade. A tier whose output can be delayed, like a human-in-the-loop agent or an asynchronous agent, must declare an output key, since the planner reads its answer from the scope: the grade of an asynchronous tier waits for its answer, and the answer of a human is graded when the cascade is resumed.

The grade is a relevance and completeness signal, not a proof of correctness: a decision model can judge whether an answer addresses the request, but it cannot verify facts. Probabilities are not calibrated in the same way by every decision model, so the acceptance threshold must be tuned on the decision model in use and tuned again when it changes. The request and the answers are untrusted input to the grade, so a crafted request or answer can influence it: the cascade trades cost against quality, it is not a security or review boundary. A failure of the decision model fails the invocation of the cascade.

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 ConfidenceCascadePlanner(decisionModel, 0.5), while the decision model can be shared.

  • Constructor Details

    • ConfidenceCascadePlanner

      public ConfidenceCascadePlanner(DecisionModel decisionModel, double acceptanceThreshold)
      Creates a cascade accepting the answer of a tier when the probability that it fully and correctly addresses the request is at least the given threshold.

      When the cascade is invoked, before calling the first tier, it fails with an IllegalArgumentException if the cascade agent is not a typed agent interface with at least one argument to send to the decision model, if one of its arguments is named candidateAnswer, or if it has fewer than two subagents.

      Parameters:
      decisionModel - the decision model grading the answer of each tier
      acceptanceThreshold - the minimum probability of "yes" for an answer to be accepted, strictly between 0 and 1
      Throws:
      IllegalArgumentException - if decisionModel is null, or if acceptanceThreshold is not strictly between 0 and 1

    • ConfidenceCascadePlanner

      public ConfidenceCascadePlanner(DecisionModel decisionModel, double acceptanceThreshold, String acceptanceCriterion)
      Creates a cascade accepting the answer of a tier when the probability that it fully and correctly addresses the request, according to the given acceptance criterion, is at least the given threshold.

      When the cascade is invoked, before calling the first tier, it fails with an IllegalArgumentException if the cascade agent is not a typed agent interface with at least one argument to send to the decision model, if one of its arguments is named candidateAnswer, or if it has fewer than two subagents.

      Parameters:
      decisionModel - the decision model grading the answer of each tier
      acceptanceThreshold - the minimum probability of "yes" for an answer to be accepted, strictly between 0 and 1
      acceptanceCriterion - a description of when the answer should be accepted, sent to the decision model as the yesWhen description of the grading question, or null for none
      Throws:
      IllegalArgumentException - if decisionModel is null, if acceptanceThreshold is not strictly between 0 and 1, or if acceptanceCriterion is blank

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