|
This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0! |
Tool Argument Augmentation
Spring AI provides a utility for dynamic augmentation of tool input schemas with additional arguments. This lets you capture extra information from the model — such as reasoning, confidence, or metadata — without modifying the underlying tool implementation. The model sees the augmented schema and fills in the extra fields; your code receives them via a consumer; the original tool receives only its expected arguments, unchanged.
Common use cases:
-
Inner thinking / reasoning — capture the model’s step-by-step reasoning before executing a tool.
-
Memory enhancement — extract insights to store in long-term memory.
-
Analytics & tracking — collect metadata, user intent, or usage patterns.
-
Multi-agent coordination — pass agent identifiers or coordination signals.
Quick Start
Define the augmented arguments as a Java record:
public record AgentThinking(
@ToolParam(description = "Your reasoning for calling this tool", required = true)
String innerThought,
@ToolParam(description = "Confidence level (low, medium, high)", required = false)
String confidence
) {}
Wrap your tools with AugmentedToolCallbackProvider:
AugmentedToolCallbackProvider<AgentThinking> provider = AugmentedToolCallbackProvider
.<AgentThinking>builder()
.toolObject(new WeatherTools()) // wrap the original tools
.argumentType(AgentThinking.class) // augmentation schema type
.argumentConsumer(event -> { // receives the augmented arguments; required
AgentThinking thinking = event.arguments();
log.info("Tool: {} | Reasoning: {}", event.toolDefinition().name(), thinking.innerThought());
})
.removeExtraArgumentsAfterProcessing(true)
.build();
ChatClient chatClient = ChatClient.builder(chatModel)
.defaultTools(provider)
.build();
The LLM sees the augmented schema with your additional fields.
Your consumer receives the AgentThinking record; the original tool receives only its expected arguments.
Core Components
-
AugmentedToolCallbackProvider<T>— wraps tool objects or providers, augmenting all tools with the specified record type. -
AugmentedToolCallback<T>— wraps individualToolCallbackinstances. -
AugmentedArgumentEvent<T>— containstoolDefinition(),rawInput(), andarguments()for consumers. -
ToolInputSchemaAugmenter— low-level utility for schema manipulation.
The removeExtraArgumentsAfterProcessing option of AugmentedToolCallbackProvider (default true) controls whether augmented arguments are passed to the original tool; the AugmentedToolCallback constructor requires it.
Set it to false if the tool can ignore extra fields and you want them preserved in the input.