Package com.aispect.agent.core

Class AbstractGraphAgent<T,R,F>

java.lang.Object
com.aispect.agent.core.AbstractGraphAgent<T,R,F>
Type Parameters:
T - The original parameters of the proxy method and the data type of the calling context
R - The expected return result type of the proxied method
F - Global state or resource data object types that flow between nodes during graph execution (such as Graph State）
All Implemented Interfaces:
AiAgentFilter, AiGraphAgentHandler<T,R,F>, AiGraphBehaviorOrchestrator<F>, AiGraphCompleteHook, AiGraphStartHook, AiGraphTimeoutHook, AiNodeExceptionHook, AiNodeStatusHook
Direct Known Subclasses:
DynamicWorkflowGraphAgent
public abstract class AbstractGraphAgent<T,R,F> extends Object implements AiGraphAgentHandler<T,R,F>
abstract schema agent (Graph Agent) Handle base classes.

This class implements AiGraphAgentHandler The interface provides a default skeleton implementation for complex agents based on graph structure orchestration. Developers can implement customized multi-node workflows by inheriting this class (Workflow）、Conditional branch scheduling, and resources/The flow of status. This class provides various life cycle hooks in advance (Hook）A default empty implementation or a conservative strategy (such as aborting on exception) to reduce boilerplate code for subclasses.

  • Constructor Details

    • AbstractGraphAgent

      public AbstractGraphAgent()

  • Method Details

    • shouldProcess

      public boolean shouldProcess(Object[] args)
      Determine whether the current agent needs to intercept and process the call to this method.

      The default implementation is to always handle (return true）。Subclasses can override this method based on input parameter characteristics or global configuration. This dynamically determines whether to skip graph execution and pass directly to the next filter or native method.

      Specified by:
      shouldProcess in interface AiAgentFilter
      Parameters:
      args - The parameter list of the target method
      Returns:
      If it needs to be taken over and processed, return true；Otherwise return false

    • doFilter

      public <T1, R1> R1 doFilter(AiInvocationContext<T1> ctx, AiExecutionProxy<T1,R1> next) throws AiSpectException
      Interception and filtering logic for proxy calls.

      The default implementation is to release directly to the execution agent. Since the schema agent usually has a special processing branch in the interceptor to call directly orchestrateGraph(java.util.Map<java.lang.String, java.lang.Object>, com.aispect.api.AiInvocationContext<?>)， The implementation of this method is mainly to be compatible with the underlying unified AiAgentFilter Interface specification.

      Specified by:
      doFilter in interface AiAgentFilter
      Type Parameters:
      T1 - Generics for method input parameters
      R1 - Generic method returns result
      Parameters:
      ctx - The context of the current method call
      next - Proxy object used to continue the execution chain
      Returns:
      final execution result
      Throws:
      AiSpectException - An exception occurred during execution

    • getAiOperations

      protected AiOperations getAiOperations(AiInvocationContext<?> ctx)
      Extract core large model interactions from context API。

      Provide a convenience method for subclasses to easily obtain and execute in each node AI Utility class for generating tasks or dialogue capabilities.

      Parameters:
      ctx - The context object for the current proxy method call
      Returns:
      Provides unified model request operations AiOperations Example

    • orchestrateGraph

      public abstract F orchestrateGraph(Map<String,Object> nodeResources, AiInvocationContext<?> ctx) throws AiSpectException
      Core method: Coordinating and orchestrating schema behaviors.

      Subclasses must implement this method to define a specific graph workflow. Multiple nodes can be scheduled here (Node）、Connect edges (Edge）， and manage graph state resources <F> Delivery and changes throughout the life cycle.

      Specified by:
      orchestrateGraph in interface AiGraphBehaviorOrchestrator<T>
      Parameters:
      nodeResources - Available node resources provided for graph scheduling,Key is the identification name of the node,Value For a specific functional function or object
      ctx - The context of the current proxy method invocation
      Returns:
      The final state after the graph is executed/The processing result is of type <F>
      Throws:
      AiSpectException - Exceptions that occur during orchestration

    • onGraphStart

      public void onGraphStart(AiInvocationContext<?> ctx)
      A hook that triggers the start of graph execution.

      exist orchestrateGraph(java.util.Map<java.lang.String, java.lang.Object>, com.aispect.api.AiInvocationContext<?>) Called by the framework just before processing begins. It can be used to initialize monitoring indicators, record startup logs and other operations.

      Specified by:
      onGraphStart in interface AiGraphStartHook
      Parameters:
      ctx - The calling context of the current method

    • onGraphComplete

      public void onGraphComplete(AiInvocationContext<?> ctx, Object finalResult)
      A hook that triggers graph execution completion.

      It is called by the framework when the entire graph is scheduled and is about to exit the interception phase. It can be used for resource cleaning, indicator reporting or summary log recording.

      Specified by:
      onGraphComplete in interface AiGraphCompleteHook
      Parameters:
      ctx - The calling context of the current method
      finalResult - The final result or status of the graph execution output

    • onNodeStatusChange

      public void onNodeStatusChange(String nodeName, String status, AiInvocationContext<?> ctx)
      Hooks that trigger status changes of specific nodes.

      When a specific node in the graph (Node）When it starts, ends, is suspended or skipped, it can be automatically triggered by the orchestration engine to monitor the detailed progress of the graph operation.

      Specified by:
      onNodeStatusChange in interface AiNodeStatusHook
      Parameters:
      nodeName - The name or ID of the node where the status change occurred
      status - The current new state of the node (such as:STARTING, COMPLETED, SKIPPED）
      ctx - The calling context of the current method

    • onNodeException

      public NodeExceptionStrategy onNodeException(String nodeName, Throwable ex, AiInvocationContext<?> ctx)
      Trigger the node to execute the hook when an exception occurs, and decide on the exception handling strategy.

      The default policy is ABORT（Abort the execution of the entire graph). Subclasses can override this method and retry strategies based on different nodes (RETRY）、Ignore and skip (SKIP）Wait for dynamic decision-making.

      Specified by:
      onNodeException in interface AiNodeExceptionHook
      Parameters:
      nodeName - The name of the node that threw the exception
      ex - specific exception object
      ctx - The calling context of the current method
      Returns:
      NodeExceptionStrategy Returns the expected exception follow-up handling strategy

    • onGraphTimeout

      public void onGraphTimeout(AiInvocationContext<?> ctx, long timeoutMs)
      A hook that triggers a timeout for the entire graph execution.

      Called when the graph running time exceeds the maximum time limit set by the system or annotation. Can be used for graceful degradation after timeout (Fallback）Or force cleanup efforts.

      Specified by:
      onGraphTimeout in interface AiGraphTimeoutHook
      Parameters:
      ctx - The calling context of the current method
      timeoutMs - Threshold (milliseconds) to configure or trigger a timeout