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

Class AsyncToolCallbackAdapter

java.lang.Object
com.alibaba.cloud.ai.graph.agent.tool.AsyncToolCallbackAdapter
All Implemented Interfaces:
AsyncToolCallback, StateAwareToolCallback, org.springframework.ai.tool.ToolCallback
public class AsyncToolCallbackAdapter extends Object implements AsyncToolCallback
Adapter that wraps synchronous ToolCallback implementations to provide asynchronous execution capabilities.

This adapter enables existing synchronous tools (such as @Tool annotated methods, FunctionToolCallback, MethodToolCallback, and MCP tools) to benefit from the async execution infrastructure without requiring user code changes.

The adapter follows the LangChain pattern of running synchronous tools in an executor to achieve parallel execution. This is especially useful when multiple independent tools need to execute concurrently.

Example usage:


 // Wrap a sync tool for async execution
 ToolCallback syncTool = getSomeSyncTool();
 AsyncToolCallback asyncTool = AsyncToolCallbackAdapter.wrapIfNeeded(syncTool, executor);

 // Use the wrapped tool in async context
 CompletableFuture<String> future = asyncTool.callAsync(args, context);

Note: Wrapped sync tools cannot be truly cancelled since they are blocking operations. The adapter provides async semantics but cancellation will only take effect after the synchronous operation completes.

Since:
1.0.0
Author:
disaster
See Also:

  • Constructor Details

    • AsyncToolCallbackAdapter

      public AsyncToolCallbackAdapter(org.springframework.ai.tool.ToolCallback delegate, Executor executor)
      Creates a new adapter with the default timeout of 5 minutes.
      Parameters:
      delegate - the synchronous tool callback to wrap
      executor - the executor to use for async execution

    • AsyncToolCallbackAdapter

      public AsyncToolCallbackAdapter(org.springframework.ai.tool.ToolCallback delegate, Executor executor, Duration timeout)
      Creates a new adapter with a custom timeout.
      Parameters:
      delegate - the synchronous tool callback to wrap
      executor - the executor to use for async execution
      timeout - the timeout duration for tool execution

  • Method Details

    • callAsync

      public CompletableFuture<String> callAsync(String arguments, org.springframework.ai.chat.model.ToolContext context)
      Asynchronously executes the wrapped synchronous tool.

      The synchronous tool's call method is executed in the configured executor, allowing it to run concurrently with other tools.

      Specified by:
      callAsync in interface AsyncToolCallback
      Parameters:
      arguments - the tool arguments as JSON string
      context - the tool execution context
      Returns:
      a CompletableFuture that will complete with the result string

    • getTimeout

      public Duration getTimeout()
      Description copied from interface: AsyncToolCallback
      Returns the timeout duration for this tool execution.
      Specified by:
      getTimeout in interface AsyncToolCallback
      Returns:
      the timeout duration, defaults to 5 minutes

    • getToolDefinition

      public org.springframework.ai.tool.definition.ToolDefinition getToolDefinition()
      Specified by:
      getToolDefinition in interface org.springframework.ai.tool.ToolCallback

    • getToolMetadata

      public org.springframework.ai.tool.metadata.ToolMetadata getToolMetadata()
      Specified by:
      getToolMetadata in interface org.springframework.ai.tool.ToolCallback

    • call

      public String call(String toolInput)
      Specified by:
      call in interface org.springframework.ai.tool.ToolCallback

    • call

      public String call(String toolInput, org.springframework.ai.chat.model.ToolContext toolContext)
      Description copied from interface: AsyncToolCallback
      Synchronous fallback implementation. Blocks until the async operation completes.

      This method unwraps CompletionException to expose the original exception, making error handling more intuitive for callers.

      Specified by:
      call in interface AsyncToolCallback
      Specified by:
      call in interface org.springframework.ai.tool.ToolCallback
      Parameters:
      toolInput - the tool arguments as JSON string
      toolContext - the tool execution context
      Returns:
      the result string

    • getDelegate

      public org.springframework.ai.tool.ToolCallback getDelegate()
      Returns the wrapped delegate callback.
      Returns:
      the original synchronous tool callback

    • wrapIfNeeded

      public static AsyncToolCallback wrapIfNeeded(org.springframework.ai.tool.ToolCallback callback, Executor executor)
      Wraps a tool callback in an async adapter if it's not already async.

      If the callback already implements AsyncToolCallback, it is returned directly without wrapping. Otherwise, a new AsyncToolCallbackAdapter is created to wrap the synchronous callback.

      Parameters:
      callback - the tool callback to potentially wrap
      executor - the executor to use for async execution
      Returns:
      an AsyncToolCallback (either the original or a wrapped adapter)

    • wrapIfNeeded

      public static AsyncToolCallback wrapIfNeeded(org.springframework.ai.tool.ToolCallback callback, Executor executor, Duration timeout)
      Wraps a tool callback in an async adapter if it's not already async.

      If the callback already implements AsyncToolCallback, it is returned directly without wrapping. Otherwise, a new AsyncToolCallbackAdapter is created to wrap the synchronous callback.

      Parameters:
      callback - the tool callback to potentially wrap
      executor - the executor to use for async execution
      timeout - the timeout duration for wrapped tool execution
      Returns:
      an AsyncToolCallback (either the original or a wrapped adapter)