Skip to content

Commit 096f140

Browse files
dimitarproynovilayaperumalg
authored andcommitted
Make tool resolution fallback configurable
Introduce a `spring.ai.tools.resolution.fallback.enabled` property (and a matching `resolutionFallbackEnabled` builder switch on `DefaultToolCallingManager`) that controls whether a tool absent from a request's tool callbacks may be resolved by name through the `ToolCallbackResolver` and executed. The fallback is disabled by default, so the tools attached to a request are the only ones executable for it. Closes #6751 Signed-off-by: Dimitar Proynov <[email protected]>
1 parent d89e4a4 commit 096f140

9 files changed

Lines changed: 245 additions & 10 deletions

File tree

‎auto-configurations/models/tool/spring-ai-autoconfigure-model-tool/src/main/java/org/springframework/ai/model/tool/autoconfigure/ToolCallingAutoConfiguration.java‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,8 @@ ToolCallingManager toolCallingManager(ToolCallbackResolver toolCallbackResolver,
141141
var builder = ToolCallingManager.builder()
142142
.observationRegistry(observationRegistry.getIfUnique(() -> ObservationRegistry.NOOP))
143143
.toolCallbackResolver(toolCallbackResolver)
144-
.toolExecutionExceptionProcessor(toolExecutionExceptionProcessor);
144+
.toolExecutionExceptionProcessor(toolExecutionExceptionProcessor)
145+
.resolutionFallbackEnabled(properties.getResolution().getFallback().isEnabled());
145146

146147
ToolCallingProperties.Limits limits = properties.getLimits();
147148

‎auto-configurations/models/tool/spring-ai-autoconfigure-model-tool/src/main/java/org/springframework/ai/model/tool/autoconfigure/ToolCallingProperties.java‎

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
* Configuration properties for tool calling.
3232
*
3333
* @author Thomas Vitale
34+
* @author Dimitar Proynov
3435
* @since 1.0.0
3536
*/
3637
@ConfigurationProperties(ToolCallingProperties.CONFIG_PREFIX)
@@ -40,16 +41,22 @@ public class ToolCallingProperties {
4041

4142
private final Observations observations = new Observations();
4243

44+
private final Resolution resolution = new Resolution();
45+
46+
private final Limits limits = new Limits();
47+
4348
public Observations getObservations() {
4449
return this.observations;
4550
}
4651

47-
private final Limits limits = new Limits();
48-
4952
public Limits getLimits() {
5053
return this.limits;
5154
}
5255

56+
public Resolution getResolution() {
57+
return this.resolution;
58+
}
59+
5360
/**
5461
* If true, tool calling errors are thrown as exceptions for the caller to handle. If
5562
* false, errors are converted to messages and sent back to the AI model, allowing it
@@ -160,4 +167,40 @@ public void setOnLimitExceeded(ToolCallLimitBehavior onLimitExceeded) {
160167

161168
}
162169

170+
public static class Resolution {
171+
172+
private final Fallback fallback = new Fallback();
173+
174+
public Fallback getFallback() {
175+
return this.fallback;
176+
}
177+
178+
public static class Fallback {
179+
180+
/**
181+
* Whether a requested tool that is absent from the request's tool callbacks
182+
* may be resolved by name through the {@code ToolCallbackResolver} (backed by
183+
* every {@code ToolCallback} bean in the application context) and executed.
184+
* <p>
185+
* Disabled by default: the tools attached to a request are the only tools
186+
* that can be executed for that request.
187+
* <p>
188+
* <strong>Enable with care.</strong> When enabled, any tool reachable through
189+
* the resolver becomes executable whenever the model names it, regardless of
190+
* what the request attached — including risk-tier and destructive tools.
191+
*/
192+
private boolean enabled = false;
193+
194+
public boolean isEnabled() {
195+
return this.enabled;
196+
}
197+
198+
public void setEnabled(boolean enabled) {
199+
this.enabled = enabled;
200+
}
201+
202+
}
203+
204+
}
205+
163206
}

‎auto-configurations/models/tool/spring-ai-autoconfigure-model-tool/src/test/java/org/springframework/ai/model/tool/autoconfigure/ToolCallingAutoConfigurationTests.java‎

Lines changed: 34 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616

1717
package org.springframework.ai.model.tool.autoconfigure;
1818

19+
import java.lang.reflect.Field;
1920
import java.util.ArrayList;
2021
import java.util.List;
2122

@@ -204,6 +205,31 @@ void throwExceptionOnErrorEnabled() {
204205
});
205206
}
206207

208+
@Test
209+
void toolCallingManagerHasResolutionFallbackDisabledByDefault() {
210+
new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(ToolCallingAutoConfiguration.class))
211+
.run(context -> {
212+
var toolCallingManager = context.getBean(DefaultToolCallingManager.class);
213+
assertThat(resolutionFallbackEnabled(toolCallingManager)).isFalse();
214+
});
215+
}
216+
217+
@Test
218+
void toolCallingManagerHasResolutionFallbackEnabledWhenPropertySet() {
219+
new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(ToolCallingAutoConfiguration.class))
220+
.withPropertyValues("spring.ai.tools.resolution.fallback.enabled=true")
221+
.run(context -> {
222+
var toolCallingManager = context.getBean(DefaultToolCallingManager.class);
223+
assertThat(resolutionFallbackEnabled(toolCallingManager)).isTrue();
224+
});
225+
}
226+
227+
private static boolean resolutionFallbackEnabled(DefaultToolCallingManager toolCallingManager) {
228+
Field field = ReflectionUtils.findField(DefaultToolCallingManager.class, "resolutionFallbackEnabled");
229+
ReflectionUtils.makeAccessible(field);
230+
return (boolean) ReflectionUtils.getField(field, toolCallingManager);
231+
}
232+
207233
@Test
208234
void toolCallbackResolverDoesNotUseMcpToolCallbackProviders() {
209235
new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(ToolCallingAutoConfiguration.class))
@@ -359,7 +385,8 @@ void toolCallLimitsDefaultAppliesFiftyTotalLimit() {
359385
@Test
360386
void maxCallsPerToolPropertySetToUnlimitedSentinelDisablesDefaultLimit() {
361387
new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(ToolCallingAutoConfiguration.class))
362-
.withPropertyValues("spring.ai.tools.limits.max-calls-per-tool-default=-1")
388+
.withPropertyValues("spring.ai.tools.limits.max-calls-per-tool-default=-1",
389+
"spring.ai.tools.resolution.fallback.enabled=true")
363390
.withUserConfiguration(Config.class)
364391
.run(context -> {
365392
var toolCallingManager = context.getBean(ToolCallingManager.class);
@@ -379,7 +406,8 @@ void maxCallsPerToolPropertySetToUnlimitedSentinelDisablesDefaultLimit() {
379406
void maxTotalToolCallsPropertySetToUnlimitedSentinelDisablesDefaultLimit() {
380407
new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(ToolCallingAutoConfiguration.class))
381408
.withPropertyValues("spring.ai.tools.limits.max-calls-per-tool-default=-1",
382-
"spring.ai.tools.limits.max-total-tool-calls=-1")
409+
"spring.ai.tools.limits.max-total-tool-calls=-1",
410+
"spring.ai.tools.resolution.fallback.enabled=true")
383411
.withUserConfiguration(Config.class)
384412
.run(context -> {
385413
var toolCallingManager = context.getBean(ToolCallingManager.class);
@@ -398,7 +426,8 @@ void maxTotalToolCallsPropertySetToUnlimitedSentinelDisablesDefaultLimit() {
398426
@Test
399427
void maxCallsPerToolOverrideSetToUnlimitedSentinelExemptsToolFromDefaultLimit() {
400428
new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(ToolCallingAutoConfiguration.class))
401-
.withPropertyValues("spring.ai.tools.limits.max-calls-per-tool.getForecast=-1")
429+
.withPropertyValues("spring.ai.tools.limits.max-calls-per-tool.getForecast=-1",
430+
"spring.ai.tools.resolution.fallback.enabled=true")
402431
.withUserConfiguration(Config.class)
403432
.run(context -> {
404433
var toolCallingManager = context.getBean(ToolCallingManager.class);
@@ -451,7 +480,8 @@ void maxCallsPerToolOverridesPropertyAppliesPerTool() {
451480
void excludedToolsPropertyBypassesPerToolLimit() {
452481
new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(ToolCallingAutoConfiguration.class))
453482
.withPropertyValues("spring.ai.tools.limits.max-calls-per-tool-default=1",
454-
"spring.ai.tools.limits.excluded-tools=getForecast")
483+
"spring.ai.tools.limits.excluded-tools=getForecast",
484+
"spring.ai.tools.resolution.fallback.enabled=true")
455485
.withUserConfiguration(Config.class)
456486
.run(context -> {
457487
var toolCallingManager = context.getBean(ToolCallingManager.class);

‎models/spring-ai-google-genai/src/test/java/org/springframework/ai/google/genai/schema/GoogleGenAiToolCallingManagerTests.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ void executeToolCallsDelegatesToWrappedManager() {
5656
ToolCallbackResolver toolCallbackResolver = new StaticToolCallbackResolver(List.of(toolCallback));
5757
ToolCallingManager delegate = DefaultToolCallingManager.builder()
5858
.toolCallbackResolver(toolCallbackResolver)
59+
.resolutionFallbackEnabled(true)
5960
.build();
6061
GoogleGenAiToolCallingManager manager = new GoogleGenAiToolCallingManager(delegate);
6162

@@ -81,6 +82,7 @@ void executeToolCallsPropagatesToolCallLimitExceededExceptionFromDelegate() {
8182
ToolCallbackResolver toolCallbackResolver = new StaticToolCallbackResolver(List.of(toolCallback));
8283
ToolCallingManager delegate = DefaultToolCallingManager.builder()
8384
.toolCallbackResolver(toolCallbackResolver)
85+
.resolutionFallbackEnabled(true)
8486
.maxCallsPerTool("toolA", 1)
8587
.build();
8688
GoogleGenAiToolCallingManager manager = new GoogleGenAiToolCallingManager(delegate);

‎spring-ai-docs/src/main/antora/modules/ROOT/pages/api/tools.adoc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -890,6 +890,23 @@ ToolCallbackResolver toolCallbackResolver(List<ToolCallback> toolCallbacks) {
890890

891891
The resolver is used internally by `ToolCallingManager` to support both xref:#the-tool-calling-loop[advisor-controlled execution] and xref:#user-controlled-tool-execution[user-controlled execution].
892892

893+
To enable the behavior — where a tool known to the resolver, but not attached to the request may be resolved by name and executed — enable the resolution fallback:
894+
895+
[source,properties]
896+
----
897+
spring.ai.tools.resolution.fallback.enabled=true
898+
----
899+
900+
[cols="6,3,1", stripes=even]
901+
|====
902+
| Property | Description | Default
903+
| `spring.ai.tools.resolution.fallback.enabled` | If `true`, a requested tool that is absent from the request's tool callbacks may be resolved by name through the `ToolCallbackResolver` and executed. If `false`, only the tools attached to the request can be executed. | `false`
904+
|====
905+
906+
When constructing a `ToolCallingManager` directly, the same switch is available on the builder via `.resolutionFallbackEnabled(true)` (default `false`).
907+
908+
WARNING: Enabling the resolution fallback makes every tool reachable through the resolver executable whenever the model names it, regardless of what a request attached — including risk-tier and destructive tools. Enable it only when you fully control which tools the resolver exposes.
909+
893910
[[observability]]
894911
== Observability
895912

‎spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -302,6 +302,31 @@ else if (data instanceof String s) {
302302
}
303303
----
304304

305+
=== Tool Resolution Fallback Disabled by Default
306+
307+
The fallback that resolves and executes tools registered as beans, but not attached to a request has been disabled by default.
308+
Previously, when the model returned a tool call for a tool that was not attached to the request, `DefaultToolCallingManager` fell back to the application-wide `ToolCallbackResolver` (backed by every `ToolCallback` bean in the application context) and executed the resolved tool.
309+
Starting with 2.0.1, the tools attached to a request — via `.tools(...)`, `.defaultTools(...)`, or `ToolCallingChatOptions.toolCallbacks(...)` — are the only tools that can be executed for that request.
310+
311+
To restore the previous behavior, re-enable the resolution fallback:
312+
313+
[source,properties]
314+
----
315+
spring.ai.tools.resolution.fallback.enabled=true
316+
----
317+
318+
When constructing a `ToolCallingManager` directly, use the builder switch instead:
319+
320+
[source,java]
321+
----
322+
ToolCallingManager toolCallingManager = ToolCallingManager.builder()
323+
.toolCallbackResolver(toolCallbackResolver)
324+
.resolutionFallbackEnabled(true) // default is false
325+
.build();
326+
----
327+
328+
See xref:api/tools.adoc#tool-resolution[Tool Resolution] for details.
329+
305330
[[upgrading-to-2-0-0]]
306331
== Upgrading to 2.0.0
307332

‎spring-ai-model/src/main/java/org/springframework/ai/model/tool/DefaultToolCallingManager.java‎

Lines changed: 50 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@
6060
* @author Thomas Vitale
6161
* @author chabinhwang
6262
* @author Christian Tzolov
63+
* @author Dimitar Proynov
6364
* @since 1.0.0
6465
*/
6566
public final class DefaultToolCallingManager implements ToolCallingManager {
@@ -80,6 +81,8 @@ public final class DefaultToolCallingManager implements ToolCallingManager {
8081
private static final ToolExecutionExceptionProcessor DEFAULT_TOOL_EXECUTION_EXCEPTION_PROCESSOR
8182
= DefaultToolExecutionExceptionProcessor.builder().build();
8283

84+
private static final boolean DEFAULT_RESOLUTION_FALLBACK_ENABLED = false;
85+
8386
private static final String POSSIBLE_LLM_TOOL_NAME_CHANGE_WARNING_START = "LLM may have adapted the tool name '";
8487
private static final String POSSIBLE_LLM_TOOL_NAME_CHANGE_WARNING_END
8588
= "', especially if the name was truncated due to length limits. If this is the case, you can customize the prefixing and processing logic using McpToolNamePrefixGenerator";
@@ -111,17 +114,44 @@ public final class DefaultToolCallingManager implements ToolCallingManager {
111114

112115
private final ToolCallLimits toolCallLimits;
113116

117+
/**
118+
* Whether a call to a tool that is not part of the request's tool callbacks may still
119+
* be executed by resolving it through the {@link ToolCallbackResolver}. When
120+
* {@code false} (the default), the tools attached to the request are the only tools
121+
* that can be executed.
122+
*/
123+
private final boolean resolutionFallbackEnabled;
124+
114125
private ToolCallingObservationConvention observationConvention = DEFAULT_OBSERVATION_CONVENTION;
115126

116127
public DefaultToolCallingManager(ObservationRegistry observationRegistry, ToolCallbackResolver toolCallbackResolver,
117128
ToolExecutionExceptionProcessor toolExecutionExceptionProcessor) {
118129
this(observationRegistry, toolCallbackResolver, toolExecutionExceptionProcessor,
119130
new ToolCallLimits(DEFAULT_MAX_CALLS_PER_TOOL, Map.of(), Set.of(), DEFAULT_MAX_TOTAL_TOOL_CALLS,
120-
ToolCallLimitBehavior.THROW));
131+
ToolCallLimitBehavior.THROW),
132+
DEFAULT_RESOLUTION_FALLBACK_ENABLED);
121133
}
122134

123135
DefaultToolCallingManager(ObservationRegistry observationRegistry, ToolCallbackResolver toolCallbackResolver,
124136
ToolExecutionExceptionProcessor toolExecutionExceptionProcessor, ToolCallLimits toolCallLimits) {
137+
this(observationRegistry, toolCallbackResolver, toolExecutionExceptionProcessor, toolCallLimits,
138+
DEFAULT_RESOLUTION_FALLBACK_ENABLED);
139+
}
140+
141+
/**
142+
* Create a {@link DefaultToolCallingManager}.
143+
* @param observationRegistry the observation registry
144+
* @param toolCallbackResolver the resolver consulted for name-based tool resolution
145+
* @param toolExecutionExceptionProcessor the processor for tool execution exceptions
146+
* @param toolCallLimits the limits applied to tool calls within a turn
147+
* @param resolutionFallbackEnabled whether tools that are not part of the request's
148+
* tool callbacks may be resolved and executed via the {@code toolCallbackResolver};
149+
* defaults to {@code false} so that the request's tool callbacks bound execution
150+
* @since 2.0.1
151+
*/
152+
DefaultToolCallingManager(ObservationRegistry observationRegistry, ToolCallbackResolver toolCallbackResolver,
153+
ToolExecutionExceptionProcessor toolExecutionExceptionProcessor, ToolCallLimits toolCallLimits,
154+
boolean resolutionFallbackEnabled) {
125155
Assert.notNull(observationRegistry, "observationRegistry cannot be null");
126156
Assert.notNull(toolCallbackResolver, "toolCallbackResolver cannot be null");
127157
Assert.notNull(toolExecutionExceptionProcessor, "toolCallExceptionConverter cannot be null");
@@ -131,6 +161,7 @@ public DefaultToolCallingManager(ObservationRegistry observationRegistry, ToolCa
131161
this.toolCallbackResolver = toolCallbackResolver;
132162
this.toolExecutionExceptionProcessor = toolExecutionExceptionProcessor;
133163
this.toolCallLimits = toolCallLimits;
164+
this.resolutionFallbackEnabled = resolutionFallbackEnabled;
134165
}
135166

136167
@Override
@@ -255,7 +286,7 @@ private InternalToolExecutionResult executeToolCall(Prompt prompt, AssistantMess
255286
ToolCallback toolCallback = toolCallbacks.stream()
256287
.filter(tool -> toolName.equals(tool.getToolDefinition().name()))
257288
.findFirst()
258-
.orElseGet(() -> this.toolCallbackResolver.resolve(toolName));
289+
.orElseGet(() -> this.resolutionFallbackEnabled ? this.toolCallbackResolver.resolve(toolName) : null);
259290

260291
if (toolCallback == null) {
261292
if (logger.isWarnEnabled()) {
@@ -348,6 +379,8 @@ public final static class Builder {
348379

349380
private ToolCallLimitBehavior onLimitExceeded = ToolCallLimitBehavior.THROW;
350381

382+
private boolean resolutionFallbackEnabled = DEFAULT_RESOLUTION_FALLBACK_ENABLED;
383+
351384
private Builder() {
352385
}
353386

@@ -448,11 +481,25 @@ public Builder onLimitExceeded(ToolCallLimitBehavior onLimitExceeded) {
448481
return this;
449482
}
450483

484+
/**
485+
* Whether a call to a tool that is not part of the request's tool callbacks may
486+
* still be executed by resolving it through the {@link ToolCallbackResolver}.
487+
* Defaults to {@code false}, so that the tools attached to a request bound what
488+
* can be executed for that request.
489+
* @param resolutionFallbackEnabled {@code true} to allow name-based resolution of
490+
* tools absent from the request via the resolver
491+
* @since 2.0.1
492+
*/
493+
public Builder resolutionFallbackEnabled(boolean resolutionFallbackEnabled) {
494+
this.resolutionFallbackEnabled = resolutionFallbackEnabled;
495+
return this;
496+
}
497+
451498
public DefaultToolCallingManager build() {
452499
ToolCallLimits toolCallLimits = new ToolCallLimits(this.defaultMaxCallsPerTool, this.maxCallsPerTool,
453500
this.toolsExcludedFromLimit, this.maxTotalToolCalls, this.onLimitExceeded);
454501
return new DefaultToolCallingManager(this.observationRegistry, this.toolCallbackResolver,
455-
this.toolExecutionExceptionProcessor, toolCallLimits);
502+
this.toolExecutionExceptionProcessor, toolCallLimits, this.resolutionFallbackEnabled);
456503
}
457504

458505
}

0 commit comments

Comments
 (0)