Interface ToolExecutor

All Known Implementing Classes:
DefaultToolExecutor, McpToolExecutor
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface ToolExecutor
A low-level executor/handler of a ToolExecutionRequest.

  • Method Details

    • execute

      String execute(ToolExecutionRequest request, Object memoryId)
      Executes a tool request.
      Parameters:
      request - The tool execution request. Contains tool name and arguments.
      memoryId - The ID of the chat memory. .
      Returns:
      The result of the tool execution that will be sent to the LLM.

    • executeWithContext

      default ToolExecutionResult executeWithContext(ToolExecutionRequest request, InvocationContext context)
      Executes a tool request. Override this method if you wish to: 
      - access the InvocationParameters when passing extra data into the tool
- propagate the tool result object (ToolExecutionResult.result()) into the ToolExecution
      Parameters:
      request - The tool execution request. Contains tool name and arguments.
      context - The AI Service invocation context, contains ChatMemory ID (see MemoryId for more details), and InvocationParameters.
      Returns:
      The result of the tool execution that will be sent to the LLM.

    • executeAsync

      @Experimental default CompletableFuture<ToolExecutionResult> executeAsync(ToolExecutionRequest request, InvocationContext context)
      Non-blocking counterpart of executeWithContext(ToolExecutionRequest, InvocationContext), invoked by the asynchronous AI Service tool loop (AI Service methods returning CompletableFuture or CompletionStage), which composes the returned future instead of waiting on a thread.

      The default implementation returns a failed future carrying AsyncNotSupportedException: asynchronous AI Services are opt-in, and silently executing a tool synchronously there would block the thread delivering model responses without any visible signal. This failure is not passed to the tool error handlers (and thus never reaches the LLM) — it fails the AI Service invocation, making the gap visible.

      Override this method to use this tool with an asynchronous AI Service. If the tool performs I/O that can be initiated without holding a thread (e.g. it delegates to an asynchronous client), return that future. If blocking execution is acceptable, it can simply return CompletableFuture.completedFuture(executeWithContext(request, context)).

      Errors may be signaled either synchronously (thrown from this method) or via a failed future; the AI Service applies the configured tool error handlers to both identically.

      Parameters:
      request - The tool execution request. Contains tool name and arguments.
      context - The AI Service invocation context, contains ChatMemory ID (see MemoryId for more details), and InvocationParameters.
      Returns:
      a CompletableFuture of the result of the tool execution that will be sent to the LLM
      Since:
      1.20.0