Package com.alibaba.cloud.ai.graph.agent.hook

Interface Hook

All Superinterfaces:
Prioritized
All Known Implementing Classes:
AgentHook, HumanInTheLoopHook, InstructionAgentHook, InterruptionHook, MessagesAgentHook, MessagesModelHook, ModelCallLimitHook, ModelHook, PIIDetectionHook, ReturnDirectModelHook, ShellToolAgentHook, SkillsAgentHook, SummarizationHook, ToolCallLimitHook
public interface Hook extends Prioritized
Hook interface for intercepting and customizing agent execution flow.

Hooks allow you to inject custom logic at specific points in the agent execution lifecycle. There are two main types of hooks:

  • AgentHook: Executes before/after the entire agent loop
  • ModelHook: Executes before/after model calls

Hooks can also provide interceptors, control flow routing, and define key strategies for state management.

See Also:

  • Method Details

    • getName

      String getName()
      Gets the unique name of this hook. The name is used to identify the hook in the execution graph.
      Returns:
      the hook name, must not be null

    • setAgentName

      void setAgentName(String agentName)
      Sets the name of the agent that owns this hook. This is typically called by the framework during agent initialization.
      Parameters:
      agentName - the agent name, must not be null

    • getAgentName

      String getAgentName()
      Gets the name of the agent that owns this hook.
      Returns:
      the agent name, or null if not set

    • getAgent

      ReactAgent getAgent()
      Gets the ReactAgent instance that owns this hook. This allows hooks to access the agent's state and configuration.
      Returns:
      the ReactAgent instance, or null if not set

    • setAgent

      void setAgent(ReactAgent agent)
      Sets the ReactAgent instance that owns this hook. This is typically called by the framework during agent initialization.
      Parameters:
      agent - the ReactAgent instance, must not be null

    • getModelInterceptors

      default List<ModelInterceptor> getModelInterceptors()
      Gets the list of model interceptors provided by this hook.

      Model interceptors can modify model requests/responses, add retry logic, implement guardrails, or provide other cross-cutting concerns.

      These interceptors will be merged with the agent's configured interceptors and applied to all model calls.

      Returns:
      list of model interceptors, empty list by default
      See Also:

    • getToolInterceptors

      default List<ToolInterceptor> getToolInterceptors()
      Gets the list of tool interceptors provided by this hook.

      Tool interceptors can modify tool calls, add retry logic, implement tool selection, or provide other cross-cutting concerns for tool execution.

      These interceptors will be merged with the agent's configured interceptors and applied to all tool calls.

      Returns:
      list of tool interceptors, empty list by default
      See Also:

    • getTools

      default List<org.springframework.ai.tool.ToolCallback> getTools()
      Gets the list of tools provided by this hook.

      Tools provided by hooks will be merged with the agent's configured tools and made available for the agent to use during execution.

      These tools will be registered with the agent's tool node and can be invoked by the agent during its execution.

      Returns:
      list of tool callbacks, empty list by default
      See Also:
      • ToolCallback

    • canJumpTo

      default List<JumpTo> canJumpTo()
      Gets the list of allowed jump destinations for this hook.

      Hooks can control the flow of execution by specifying where the agent can jump to after the hook executes. This allows hooks to redirect the execution flow based on their logic.

      Common jump destinations include:

      Returns:
      list of allowed jump destinations, empty list by default
      See Also:

    • getKeyStrategys

      default Map<String,KeyStrategy> getKeyStrategys()
      Gets the key strategies for state management.

      Key strategies define how state values are merged when updating the agent's state. This allows hooks to control how their state updates interact with the agent's state.

      Common strategies include:

      Returns:
      map of key names to their strategies, empty map by default
      See Also:

    • getHookPositions

      default HookPosition[] getHookPositions()
      Gets the positions where this hook should be executed in the agent execution flow.

      The execution order is determined by:

      1. If the implementing class has a HookPositions annotation, use its value
      2. Otherwise, use default positions based on hook type:
      3. If neither applies, return empty array (hook will not be executed)
      Returns:
      array of HookPosition values indicating where this hook should execute
      See Also:

    • getFullHookName

      static String getFullHookName(Hook hook)
      Generates the full qualified name for a hook in the execution graph.

      The full name is constructed by prefixing the hook's name with the agent hook name prefix. This ensures unique identification of hooks within the graph execution context.

      Parameters:
      hook - the hook instance, must not be null
      Returns:
      the full hook name with prefix (e.g., "agent.hook.myHook")