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

Interface LLMProvider.ToolSpec

Enclosing interface:

LLMProvider

public static interface LLMProvider.ToolSpec

A framework-agnostic tool definition that the LLM can invoke.

Unlike vendor-specific tool annotations (e.g., LangChain4j's @Tool, Spring AI's @Tool), this interface allows tools to be defined programmatically without depending on any specific AI framework.

Tool definitions are typically provided by AIController implementations through their AIController.getTools() method.

Method Summary

Modifier and Type	Method	Description
String	execute(tools.jackson.databind.JsonNode arguments)	Executes the tool with the given arguments.
String	getDescription()	Gets a human-readable description of what this tool does.
String	getName()	Gets the unique name of this tool.
String	getParametersSchema()	Gets the JSON Schema describing the parameters this tool accepts.

Method Details

getName

String getName()

Gets the unique name of this tool. The name must contain only alphanumeric characters, underscores, and hyphens, with a maximum length of 64 characters (matching the pattern ^[a-zA-Z0-9_-]{1,64}$), as required by popular LLM APIs. Names that do not match this pattern will be rejected by the orchestrator at request time. To avoid name collisions, use a namespaced name such as "MyController_updateConfig".

Returns:

the tool name, never null or empty

getDescription

String getDescription()

Gets a human-readable description of what this tool does. This description is sent to the LLM to help it decide when to invoke the tool.

Returns:

the tool description, never null

getParametersSchema

String getParametersSchema()

Gets the JSON Schema describing the parameters this tool accepts. The schema should follow the JSON Schema specification.

Example:

 {
   "type": "object",
   "properties": {
     "query": { "type": "string", "description": "The SQL query" }
   },
   "required": ["query"]
 }
 

Hand-writing the JSON is fine for small schemas but becomes error-prone as they grow. For larger schemas, a schema generator catches keyword typos and structural mistakes at compile time. When using SpringAILLMProvider, Spring AI's JsonSchemaGenerator is available without an extra dependency:

 import com.fasterxml.jackson.annotation.JsonPropertyDescription;
 import org.springframework.ai.util.json.schema.JsonSchemaGenerator;

 record UpdateGridArgs(
         @JsonPropertyDescription("The SQL query") String query) {}

 private static final String SCHEMA = JsonSchemaGenerator
         .generateForType(UpdateGridArgs.class);

 // in execute(JsonNode arguments):
 UpdateGridArgs args = new ObjectMapper().treeToValue(arguments,
         UpdateGridArgs.class);
 

For other setups, any general-purpose JSON Schema generator that produces a schema string from a typed Java class works equivalently.

Whichever approach you pick, verify the output stays inside the portable JSON Schema subset (string, integer, number, boolean, array, object, plus anyOf and enum). Generators may emit keywords such as format, pattern, or $ref that not every LLM provider accepts.

Returns:

the JSON Schema string, or null if the tool takes no parameters

execute

String execute(tools.jackson.databind.JsonNode arguments)

Executes the tool with the given arguments.

Implementations should return a human-readable result string on success. On failure, they may throw any runtime exception.

Parameters:

arguments - the tool arguments as a JsonNode matching the parameters schema

Returns:

the result of the tool execution as a string, never null