Interface Planner

All Known Implementing Classes:
BDIPlanner, BlackboardPlanner, ConditionalPlanner, DebatePlanner, GoalOrientedPlanner, LoopPlanner, P2PPlanner, ParallelMapperPlanner, ParallelPlanner, SequentialPlanner, SupervisorPlanner, VotingPlanner
public interface Planner

  • Method Summary

    Modifier and Type
    Method
    Description
    default <T extends AgentInstance>
    T
    as(Class<T> agentInstanceClass, AgentInstance agentInstance)
     
    default Action
    call(AgentInstance... agents)
    Returns an action that invokes the given agents.
    default Action
    call(List<AgentInstance> agents)
    Returns an action that invokes the given agents.
    default Action
    done()
    Returns an action signaling that the planner has completed with no explicit result.
    default Action
    done(Object result)
    Returns an action signaling that the planner has completed with the given result.
    default Map<String,Object>
    executionState()
    Returns the planner's current execution state as a map of serializable values.
    default Action
    firstAction(PlanningContext planningContext)
    Returns the first action to execute when the planner starts (or resumes).
    default void
    init(InitPlanningContext initPlanningContext)
     
    Action
    nextAction(PlanningContext planningContext)
    Determines the next action to execute based on the result of the previous agent invocation.
    default Action
    noOp()
    Returns a no-op action that yields control without invoking any agent.
    default void
    restoreExecutionState(Map<String,Object> state)
    Restores the planner's execution state from a previously saved map.
    default Action
    suspend()
    Returns an action signaling that the agentic system should suspend.
    default boolean
    terminated()
    Returns true if the planner has reached a terminal state and will not produce further actions.
    default AgenticSystemTopology
    topology()
    Returns the topology of the agentic system managed by this planner.

  • Method Details

    • init

      default void init(InitPlanningContext initPlanningContext)

    • executionState

      default Map<String,Object> executionState()
      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 restoreExecutionState(Map) and firstAction(PlanningContext) is called, the planner produces the correct resume action.

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

      Returns:
      a map of state entries to persist, or an empty map if no state needs saving

    • restoreExecutionState

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

    • firstAction

      default Action firstAction(PlanningContext planningContext)
      Returns the first action to execute when the planner starts (or resumes). Defaults to delegating to nextAction(PlanningContext).
      Parameters:
      planningContext - the current planning context
      Returns:
      the first action to execute

    • topology

      default AgenticSystemTopology topology()
      Returns the topology of the agentic system managed by this planner.
      Returns:
      the topology (defaults to AgenticSystemTopology.SEQUENCE)

    • nextAction

      Action nextAction(PlanningContext planningContext)
      Determines the next action to execute based on the result of the previous agent invocation.
      Parameters:
      planningContext - the current planning context, including the previous agent's result
      Returns:
      the next action to execute

    • terminated

      default boolean terminated()
      Returns true if the planner has reached a terminal state and will not produce further actions.
      Returns:
      true if the planner is terminated

    • noOp

      default Action noOp()
      Returns a no-op action that yields control without invoking any agent.
      Returns:
      a no-op action

    • call

      default Action call(AgentInstance... agents)
      Returns an action that invokes the given agents. Multiple agents are dispatched in parallel.
      Parameters:
      agents - the agents to invoke
      Returns:
      an agent call action

    • call

      default Action call(List<AgentInstance> agents)
      Returns an action that invokes the given agents. Multiple agents are dispatched in parallel.
      Parameters:
      agents - the agents to invoke
      Returns:
      an agent call action

    • done

      default Action done()
      Returns an action signaling that the planner has completed with no explicit result.
      Returns:
      a done action

    • done

      default Action done(Object result)
      Returns an action signaling that the planner has completed with the given result.
      Parameters:
      result - the result value
      Returns:
      a done action carrying the result

    • suspend

      default Action suspend()
      Returns an action signaling that the agentic system should suspend. The execution loop will checkpoint the scope state and release the calling thread.
      Returns:
      a suspend action

    • as

      default <T extends AgentInstance> T as(Class<T> agentInstanceClass, AgentInstance agentInstance)