Package com.vaadin.flow.component.ai.provider

Class ToolException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
com.vaadin.flow.component.ai.provider.ToolException
All Implemented Interfaces:
Serializable
public class ToolException extends RuntimeException
Signals a tool failure whose message is safe to pass back to the LLM.

Throw this from tool code — a ToolSpec.execute implementation, a controller callback, or a DatabaseProvider — when the LLM should see why the call failed so it can correct its next attempt instead of retrying blindly. The message is forwarded verbatim as the tool's error output, so you must ensure it is safe to expose: no PII, no internal identifiers beyond what the LLM already sent, no third-party error text.

Any other exception thrown from tool code is caught, logged, and replaced with a generic error message before reaching the LLM, so internal details are not leaked.

This contract applies only to tools defined through the framework-agnostic LLMProvider.ToolSpec API — the tools registered by AIController implementations and by DatabaseProvider-backed tools. Tools defined with vendor-specific annotations (LangChain4j's or Spring AI's @Tool) are executed by the vendor framework itself, whose own error handling decides what reaches the LLM — by default both frameworks relay the raw message of any exception, so neither the verbatim-forwarding nor the generic-replacement behavior described above applies to them.

Since:
25.3
Author:
Vaadin Ltd
See Also:

  • Constructor Details

    • ToolException

      public ToolException(String llmFacingMessage)
      Creates a new tool exception.
      Parameters:
      llmFacingMessage - the failure message, forwarded verbatim to the LLM

    • ToolException

      public ToolException(String llmFacingMessage, Throwable cause)
      Creates a new tool exception with a cause. Only the message is forwarded to the LLM; the cause is available for logging.
      Parameters:
      llmFacingMessage - the failure message, forwarded verbatim to the LLM
      cause - the underlying cause