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

Class ToolContextHelper

java.lang.Object
com.alibaba.cloud.ai.graph.agent.tools.ToolContextHelper
public final class ToolContextHelper extends Object
Utility class for accessing common metadata from ToolContext.

This class provides type-safe, user-friendly methods to access frequently used context data. For custom metadata or advanced use cases, you can still use ToolContextConstants keys directly with ToolContext.getContext().

Two ways to access ToolContext data:

1. Helper way (recommended for standard data):

 // Get RunnableConfig - type-safe, no casting needed
 Optional<RunnableConfig> config = ToolContextHelper.getConfig(toolContext);

 // Get OverAllState
 Optional<OverAllState> state = ToolContextHelper.getState(toolContext);

 // Get custom metadata with type safety
 Optional<String> userId = ToolContextHelper.getMetadata(toolContext, "user_id", String.class);

2. Direct key access (for custom data or batch operations):

 // Access using ToolContextConstants
 Map<String, Object> context = toolContext.getContext();
 RunnableConfig config = (RunnableConfig) context.get(ToolContextConstants.AGENT_CONFIG_CONTEXT_KEY);

 // Or access your custom keys
 Object myData = context.get("my_custom_key");
See Also:

  • Method Details

    • getConfig

      public static Optional<RunnableConfig> getConfig(@Nullable org.springframework.ai.chat.model.ToolContext toolContext)
      Get the RunnableConfig from ToolContext.

      This is a convenience method equivalent to: toolContext.getContext().get(ToolContextConstants.AGENT_CONFIG_CONTEXT_KEY)

      Parameters:
      toolContext - the tool context
      Returns:
      Optional containing RunnableConfig if present

    • getState

      public static Optional<OverAllState> getState(@Nullable org.springframework.ai.chat.model.ToolContext toolContext)
      Get the agent state (OverAllState) from ToolContext.

      This is a convenience method equivalent to: toolContext.getContext().get(ToolContextConstants.AGENT_STATE_CONTEXT_KEY)

      Parameters:
      toolContext - the tool context
      Returns:
      Optional containing OverAllState if present

    • getStateForUpdate

      public static Optional<Map<String,Object>> getStateForUpdate(@Nullable org.springframework.ai.chat.model.ToolContext toolContext)
      Get the state map for update from ToolContext. This is used when the tool needs to modify state.

      This is a convenience method equivalent to: toolContext.getContext().get(ToolContextConstants.AGENT_STATE_FOR_UPDATE_CONTEXT_KEY)

      Parameters:
      toolContext - the tool context
      Returns:
      Optional containing state map if present

    • getMetadata

      public static <T> Optional<T> getMetadata(@Nullable org.springframework.ai.chat.model.ToolContext toolContext, String key, Class<T> type)
      Get metadata value by key with type safety.

      Works with both framework keys and your custom keys:

       // Framework key via constant
 Optional<RunnableConfig> config = ToolContextHelper.getMetadata(
     toolContext, ToolContextConstants.AGENT_CONFIG_CONTEXT_KEY, RunnableConfig.class);

 // Your custom key
 Optional<String> myData = ToolContextHelper.getMetadata(toolContext, "my_key", String.class);
      Type Parameters:
      T - the type of the metadata value
      Parameters:
      toolContext - the tool context
      key - the metadata key (can be from ToolContextConstants or custom)
      type - the expected type class
      Returns:
      Optional containing typed value if present and type matches

    • getMetadataOrDefault

      public static <T> T getMetadataOrDefault(@Nullable org.springframework.ai.chat.model.ToolContext toolContext, String key, Class<T> type, T defaultValue)
      Get metadata value with default fallback.
      Type Parameters:
      T - the type of the metadata value
      Parameters:
      toolContext - the tool context
      key - the metadata key
      type - the expected type class
      defaultValue - the default value if key not found or type mismatch
      Returns:
      the value if present and type matches, otherwise defaultValue

    • hasKey

      public static boolean hasKey(@Nullable org.springframework.ai.chat.model.ToolContext toolContext, String key)
      Check if ToolContext contains a specific key.
      Parameters:
      toolContext - the tool context
      key - the key to check
      Returns:
      true if the key exists

    • getAllContext

      public static Map<String,Object> getAllContext(@Nullable org.springframework.ai.chat.model.ToolContext toolContext)
      Get all context data as a Map. Returns empty map if context is null.
      Parameters:
      toolContext - the tool context
      Returns:
      unmodifiable view of context data, or empty map