Package com.alibaba.cloud.ai.graph.agent.flow.strategy

Class AbstractFlowGraphBuildingStrategy

java.lang.Object
com.alibaba.cloud.ai.graph.agent.flow.strategy.AbstractFlowGraphBuildingStrategy
All Implemented Interfaces:
FlowGraphBuildingStrategy
Direct Known Subclasses:
ConditionalGraphBuildingStrategy, LoopGraphBuildingStrategy, ParallelGraphBuildingStrategy, RoutingGraphBuildingStrategy, SequentialGraphBuildingStrategy
public abstract class AbstractFlowGraphBuildingStrategy extends Object implements FlowGraphBuildingStrategy
Abstract base class for FlowGraphBuildingStrategy implementations. Provides common Hook processing logic and template method pattern to eliminate boilerplate code across all strategy types.

This class uses the Template Method pattern: the buildGraph(FlowGraphBuilder.FlowGraphConfig) method handles all common setup (graph creation, hook filtering, node addition, etc.), while subclasses only need to implement buildCoreGraph(FlowGraphBuilder.FlowGraphConfig) to define their specific graph structure.

Since:
2025-01-07
Author:
haojun.phj (Jackie)

  • Field Details

    • graph

      protected StateGraph graph
      The state graph being built. Accessible by subclasses.

    • rootAgent

      protected Agent rootAgent
      The root agent of the flow. Accessible by subclasses.

    • beforeAgentHooks

      protected List<Hook> beforeAgentHooks
      Hooks that execute before the agent. Accessible by subclasses.

    • afterAgentHooks

      protected List<Hook> afterAgentHooks
      Hooks that execute after the agent. Accessible by subclasses.

    • beforeModelHooks

      protected List<Hook> beforeModelHooks
      Hooks that execute before the model. Accessible by subclasses.

    • afterModelHooks

      protected List<Hook> afterModelHooks
      Hooks that execute after the model. Accessible by subclasses.

    • entryNode

      protected String entryNode
      The entry node name of the graph. Accessible by subclasses.

    • exitNode

      protected String exitNode
      The exit node name of the graph. Accessible by subclasses.

  • Constructor Details

    • AbstractFlowGraphBuildingStrategy

      public AbstractFlowGraphBuildingStrategy()

  • Method Details

    • buildGraph

      public final StateGraph buildGraph(FlowGraphBuilder.FlowGraphConfig config) throws GraphStateException
      Template method that handles all common graph building logic. Subclasses should NOT override this method. Instead, implement buildCoreGraph(FlowGraphBuilder.FlowGraphConfig).
      Specified by:
      buildGraph in interface FlowGraphBuildingStrategy
      Parameters:
      config - the flow graph configuration
      Returns:
      the constructed state graph
      Throws:
      GraphStateException - if graph construction fails

    • getRootAgent

      protected Agent getRootAgent()

    • buildCoreGraph

      protected void buildCoreGraph(FlowGraphBuilder.FlowGraphConfig config) throws GraphStateException
      Abstract method that subclasses must implement to build their specific graph structure. All common setup (graph creation, hook filtering, node addition, etc.) is already done. Subclasses can directly access protected fields: graph, rootAgent, beforeModelHooks, afterModelHooks, entryNode, exitNode.

      Note: Subclasses should NOT call connectBeforeModelHookEdges() or connectAfterModelHookEdges() in this method. Instead, override the hook methods (connectBeforeModelHooks(), connectAfterModelHooks()) if custom hook connection logic is needed.

      Parameters:
      config - the flow graph configuration
      Throws:
      GraphStateException - if graph construction fails

    • connectBeforeModelHooks

      protected void connectBeforeModelHooks() throws GraphStateException
      Connects beforeModel hook edges. Subclasses can override to customize behavior. Default implementation connects hooks in sequence to rootAgent.name().

      This method is called after buildCoreGraph() and before connectAfterModelHooks(). Subclasses that handle hook connections in buildCoreGraph() should override this method with an empty implementation to avoid duplicate edge connections.

      Throws:
      GraphStateException - if graph construction fails

    • connectAfterModelHooks

      protected void connectAfterModelHooks() throws GraphStateException
      Connects afterModel hook edges. Subclasses can override to customize behavior. Default implementation connects hooks in sequence from rootAgent.name().

      This method is called after connectBeforeModelHooks() and before connectBeforeAgentHooks(). Subclasses that handle hook connections in buildCoreGraph() should override this method with an empty implementation to avoid duplicate edge connections.

      Throws:
      GraphStateException - if graph construction fails

    • connectBeforeAgentHooks

      protected void connectBeforeAgentHooks() throws GraphStateException
      Connects beforeAgent hook edges. Subclasses rarely need to override this. Default implementation chains beforeAgent hooks and connects to the next node (either the first beforeModel hook or rootAgent).

      This method is called after connectAfterModelHooks() and before connectAfterAgentHooks().

      Throws:
      GraphStateException - if graph construction fails

    • connectAfterAgentHooks

      protected void connectAfterAgentHooks() throws GraphStateException
      Connects afterAgent hook edges. Subclasses rarely need to override this. Default implementation chains afterAgent hooks and connects to END.

      This method is called after connectBeforeAgentHooks() as the final step of hook connection.

      Throws:
      GraphStateException - if graph construction fails

    • filterHooksByPosition

      protected static List<Hook> filterHooksByPosition(List<? extends Hook> hooks, HookPosition position)
      Filter hooks by their position based on @HookPositions annotation. A hook will be included if its getHookPositions() contains the specified position. If a hook implements Prioritized interface, it will be sorted by its order. Hooks that don't implement Prioritized will maintain their original order.
      Parameters:
      hooks - the list of hooks to filter
      position - the position to filter by
      Returns:
      list of hooks that should execute at the specified position

    • addBeforeAgentHookNodesToGraph

      protected void addBeforeAgentHookNodesToGraph(StateGraph graph, List<Hook> beforeAgentHooks) throws GraphStateException
      Adds beforeAgent hook nodes to the graph.
      Parameters:
      graph - the state graph to add nodes to
      beforeAgentHooks - the list of beforeAgent hooks
      Throws:
      GraphStateException - if graph construction fails

    • addAfterAgentHookNodesToGraph

      protected void addAfterAgentHookNodesToGraph(StateGraph graph, List<Hook> afterAgentHooks) throws GraphStateException
      Adds afterAgent hook nodes to the graph.
      Parameters:
      graph - the state graph to add nodes to
      afterAgentHooks - the list of afterAgent hooks
      Throws:
      GraphStateException - if graph construction fails

    • connectBeforeModelHookEdges

      protected String connectBeforeModelHookEdges(StateGraph graph, String defaultFirstNode, List<Hook> beforeModelHooks) throws GraphStateException
      Connects beforeModel hook nodes in sequence and returns the first node name. Note: The hook nodes should already be added to the graph by addBeforeModelHookNodes(StateGraph, List). This method only handles edge connections.
      Parameters:
      graph - the state graph to add edges to
      defaultFirstNode - the default first node if no beforeModel hooks exist
      beforeModelHooks - the list of beforeModel hooks
      Returns:
      the name of the first node in the execution chain
      Throws:
      GraphStateException - if graph construction fails

    • connectAfterModelHookEdges

      protected String connectAfterModelHookEdges(StateGraph graph, String sourceNode, List<Hook> afterModelHooks) throws GraphStateException
      Connects afterModel hook nodes in sequence and returns the last node name. Note: The hook nodes should already be added to the graph by addAfterModelHookNodes(StateGraph, List). This method only handles edge connections.
      Parameters:
      graph - the state graph to add edges to
      sourceNode - the source node to connect from
      afterModelHooks - the list of afterModel hooks
      Returns:
      the name of the last node in the chain
      Throws:
      GraphStateException - if graph construction fails

    • chainBeforeAgentHooks

      protected void chainBeforeAgentHooks(StateGraph graph, List<Hook> beforeAgentHooks, String nextNode) throws GraphStateException
      Chains beforeAgent hooks in sequence and connects to the next node.
      Parameters:
      graph - the state graph
      beforeAgentHooks - the list of beforeAgent hooks
      nextNode - the next node to connect to
      Throws:
      GraphStateException - if graph construction fails

    • chainAfterAgentHooks

      protected void chainAfterAgentHooks(StateGraph graph, List<Hook> afterAgentHooks) throws GraphStateException
      Chains afterAgent hooks in sequence and connects to END.
      Parameters:
      graph - the state graph
      afterAgentHooks - the list of afterAgent hooks
      Throws:
      GraphStateException - if graph construction fails

    • determineExitNode

      protected String determineExitNode(List<Hook> afterAgentHooks)
      Determines the exit node based on afterAgent hooks.
      Parameters:
      afterAgentHooks - the list of afterAgent hooks
      Returns:
      the name of the exit node

    • determineEntryNode

      protected String determineEntryNode(Agent rootAgent, List<Hook> beforeAgentHooks, List<Hook> beforeModelHooks)
      Determines the entry node based on beforeAgent and beforeModel hooks.
      Parameters:
      rootAgent - the root agent
      beforeAgentHooks - the list of beforeAgent hooks
      beforeModelHooks - the list of beforeModel hooks
      Returns:
      the name of the entry node