Interface ToolExecutionErrorHandler

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 ToolExecutionErrorHandler
Handler for ToolExecutionExceptions thrown by a ToolExecutor.

There are two ways to handle errors:

1. Return a text message that will be sent back to the LLM, allowing it to respond appropriately (for example, by correcting the error and retrying).

2. Throw an exception: this will stop the AI service flow. Use ToolErrorContext.rawError() to access the raw error before cause-unwrapping when deciding whether to throw.

Since:
1.4.0
See Also:

  • Method Details

    • handle

      ToolErrorHandlerResult handle(Throwable error, ToolErrorContext context)
      Handles an error that occurred during tool execution.

      This method should either throw an exception or return a ToolErrorHandlerResult.text(String), which will be sent to the LLM as the result of the tool execution.

      Parameters:
      error - The actual error that occurred (cause-unwrapped). Use ToolErrorContext.rawError() for the error before unwrapping.
      context - The context in which the error occurred.
      Returns:
      The result of error handling.

    • failInvocation

      static ToolExecutionErrorHandler failInvocation()
      Returns a handler that rethrows the error, failing the AI Service invocation. Nothing about the error is sent to the LLM.

      Use this when a failing tool means the interaction cannot produce a correct answer, or when the error must not reach the LLM.

      Since:
      1.21.0

    • sendExceptionMessageToLlm

      static ToolExecutionErrorHandler sendExceptionMessageToLlm()
      Returns a handler that sends the message of the error to the LLM as the result of the tool execution, giving the LLM a chance to react to it (for example, by trying another tool or by telling the user what went wrong). The AI Service invocation continues.

      WARNING: this option can expose sensitive data. The message of an exception is usually written for developers, not for the LLM: it can contain internal application details (file paths, SQL, credentials embedded in error strings, responses of downstream services, personal data). Everything sent here reaches the LLM provider, is stored in the chat memory and can end up in the answer the user reads, in logs and in observability pipelines.

      Use this only when you know that the exception messages of all your tools are written with that in mind. Otherwise, prefer a handler that returns a generic or sanitized description of the failure, and keep the details in your logs.

      An error implementing ToolErrorVisibleToLlm is an exception: for those, the text written in ToolErrorVisibleToLlm.messageForLlm() is sent instead of the message of the exception.

      Since:
      1.21.0

    • failInvocationUnlessVisibleToLlm

      static ToolExecutionErrorHandler failInvocationUnlessVisibleToLlm()
      Returns a handler that sends ToolErrorVisibleToLlm.messageForLlm() to the LLM when the tool threw an exception implementing ToolErrorVisibleToLlm, and fails the AI Service invocation for every other exception.

      This lets the application decide, per exception, what the LLM is allowed to see: a failure the LLM can do something about (for example, "there is no order with this ID") is described to it in your own words, while an unexpected failure (a bug, a database that is down) fails the invocation instead of being hidden from you.

      If ToolErrorVisibleToLlm.messageForLlm() returns a blank text, the AI Service invocation fails as well.

      Since:
      1.21.0
      See Also:

    • sendGenericMessageToLlmUnlessVisibleToLlm

      static ToolExecutionErrorHandler sendGenericMessageToLlmUnlessVisibleToLlm(String genericMessage)
      Returns a handler that sends ToolErrorVisibleToLlm.messageForLlm() to the LLM when the tool threw an exception implementing ToolErrorVisibleToLlm, and the given generic message for every other exception. The AI Service invocation continues in both cases.

      Like failInvocationUnlessVisibleToLlm(), this never sends the message of an exception the LLM was not meant to see. Unlike it, an unexpected failure does not fail the whole AI Service invocation: the LLM learns that the tool failed and can try something else or tell the user. The price is that such a failure no longer reaches your code as an exception, so this handler logs every exception that does not implement ToolErrorVisibleToLlm at WARN level, together with its stack trace.

      Parameters:
      genericMessage - the text to send to the LLM for an exception that does not implement ToolErrorVisibleToLlm, for example "The tool failed because of an internal error.". Must not be blank.
      Since:
      1.21.0
      See Also: