feat(anthropic): add tool choice support for chat model (#4637)

Add support for Anthropic's tool_choice parameter, allowing fine-grained
control over how the model uses provided tools. This feature enables users
to force, prevent, or influence tool usage behavior.

- Add ToolChoice interface with four implementations: ToolChoiceAuto,
  ToolChoiceAny, ToolChoiceTool, and ToolChoiceNone
- Add toolChoice field to AnthropicChatOptions with builder support
- Add toolChoice parameter to ChatCompletionRequest
- Create StringToToolChoiceConverter for property binding from JSON strings
- Add integration tests for all tool choice modes
- Add documentation with usage examples

Signed-off-by: Austin Dase <[email protected]>
Co-authored-by: Christian Tzolov <[email protected]>

Author: adase11

auto-configurations/models/spring-ai-autoconfigure-model-anthropic/src/main/java/org/springframework/ai/model/anthropic/autoconfigure/AnthropicChatAutoConfiguration.java

@@ -37,6 +37,7 @@
 import org.springframework.boot.autoconfigure.web.reactive.function.client.WebClientAutoConfiguration;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Import;
 import org.springframework.retry.support.RetryTemplate;
 import org.springframework.web.client.ResponseErrorHandler;
 import org.springframework.web.client.RestClient;
@@ -57,6 +58,7 @@
 @ConditionalOnClass(AnthropicApi.class)
 @ConditionalOnProperty(name = SpringAIModelProperties.CHAT_MODEL, havingValue = SpringAIModels.ANTHROPIC,
 		matchIfMissing = true)
+@Import(StringToToolChoiceConverter.class)
 public class AnthropicChatAutoConfiguration {
 
 	@Bean

auto-configurations/models/spring-ai-autoconfigure-model-anthropic/src/main/java/org/springframework/ai/model/anthropic/autoconfigure/StringToToolChoiceConverter.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2023-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.model.anthropic.autoconfigure;
+
+import org.springframework.ai.anthropic.api.AnthropicApi;
+import org.springframework.ai.model.ModelOptionsUtils;
+import org.springframework.boot.context.properties.ConfigurationPropertiesBinding;
+import org.springframework.core.convert.converter.Converter;
+import org.springframework.stereotype.Component;
+
+/**
+ * Converter to deserialize JSON string into {@link AnthropicApi.ToolChoice}. This
+ * converter is used by Spring Boot's configuration properties binding to convert string
+ * values from application properties into ToolChoice objects.
+ *
+ * @author Christian Tzolov
+ * @since 1.0.0
+ */
+@Component
+@ConfigurationPropertiesBinding
+public class StringToToolChoiceConverter implements Converter<String, AnthropicApi.ToolChoice> {
+
+	@Override
+	public AnthropicApi.ToolChoice convert(String source) {
+		return ModelOptionsUtils.jsonToObject(source, AnthropicApi.ToolChoice.class);
+	}
+
+}

auto-configurations/models/spring-ai-autoconfigure-model-anthropic/src/test/java/org/springframework/ai/model/anthropic/autoconfigure/AnthropicPropertiesTests.java

@@ -19,6 +19,7 @@
 import org.junit.jupiter.api.Test;
 
 import org.springframework.ai.anthropic.AnthropicChatModel;
+import org.springframework.ai.anthropic.api.AnthropicApi.ToolChoiceTool;
 import org.springframework.ai.retry.autoconfigure.SpringAiRetryAutoConfiguration;
 import org.springframework.boot.autoconfigure.AutoConfigurations;
 import org.springframework.boot.autoconfigure.web.client.RestClientAutoConfiguration;
@@ -75,7 +76,9 @@ public void chatOptionsTest() {
 
 				"spring.ai.anthropic.chat.options.temperature=0.55",
 				"spring.ai.anthropic.chat.options.top-p=0.56",
-				"spring.ai.anthropic.chat.options.top-k=100"
+				"spring.ai.anthropic.chat.options.top-k=100",
+
+				"spring.ai.anthropic.chat.options.toolChoice={\"name\":\"toolChoiceFunctionName\",\"type\":\"tool\"}"
 				)
 			// @formatter:on
 			.withConfiguration(BaseAnthropicIT.anthropicAutoConfig(AnthropicChatAutoConfiguration.class))
@@ -93,6 +96,11 @@ public void chatOptionsTest() {
 				assertThat(chatProperties.getOptions().getTopK()).isEqualTo(100);
 
 				assertThat(chatProperties.getOptions().getMetadata().userId()).isEqualTo("MyUserId");
+
+				assertThat(chatProperties.getOptions().getToolChoice()).isNotNull();
+				assertThat(chatProperties.getOptions().getToolChoice().type()).isEqualTo("tool");
+				assertThat(((ToolChoiceTool) chatProperties.getOptions().getToolChoice()).name())
+					.isEqualTo("toolChoiceFunctionName");
 			});
 	}
 

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatOptions.java

@@ -60,6 +60,7 @@ public class AnthropicChatOptions implements ToolCallingChatOptions {
 	private @JsonProperty("temperature") Double temperature;
 	private @JsonProperty("top_p") Double topP;
 	private @JsonProperty("top_k") Integer topK;
+	private @JsonProperty("tool_choice") AnthropicApi.ToolChoice toolChoice;
 	private @JsonProperty("thinking") ChatCompletionRequest.ThinkingConfig thinking;
 
 	@JsonIgnore
@@ -117,6 +118,7 @@ public static AnthropicChatOptions fromOptions(AnthropicChatOptions fromOptions)
 			.temperature(fromOptions.getTemperature())
 			.topP(fromOptions.getTopP())
 			.topK(fromOptions.getTopK())
+			.toolChoice(fromOptions.getToolChoice())
 			.thinking(fromOptions.getThinking())
 			.toolCallbacks(
 					fromOptions.getToolCallbacks() != null ? new ArrayList<>(fromOptions.getToolCallbacks()) : null)
@@ -190,6 +192,14 @@ public void setTopK(Integer topK) {
 		this.topK = topK;
 	}
 
+	public AnthropicApi.ToolChoice getToolChoice() {
+		return this.toolChoice;
+	}
+
+	public void setToolChoice(AnthropicApi.ToolChoice toolChoice) {
+		this.toolChoice = toolChoice;
+	}
+
 	public ChatCompletionRequest.ThinkingConfig getThinking() {
 		return this.thinking;
 	}
@@ -291,7 +301,8 @@ public boolean equals(Object o) {
 				&& Objects.equals(this.metadata, that.metadata)
 				&& Objects.equals(this.stopSequences, that.stopSequences)
 				&& Objects.equals(this.temperature, that.temperature) && Objects.equals(this.topP, that.topP)
-				&& Objects.equals(this.topK, that.topK) && Objects.equals(this.thinking, that.thinking)
+				&& Objects.equals(this.topK, that.topK) && Objects.equals(this.toolChoice, that.toolChoice)
+				&& Objects.equals(this.thinking, that.thinking)
 				&& Objects.equals(this.toolCallbacks, that.toolCallbacks)
 				&& Objects.equals(this.toolNames, that.toolNames)
 				&& Objects.equals(this.internalToolExecutionEnabled, that.internalToolExecutionEnabled)
@@ -303,8 +314,8 @@ public boolean equals(Object o) {
 	@Override
 	public int hashCode() {
 		return Objects.hash(this.model, this.maxTokens, this.metadata, this.stopSequences, this.temperature, this.topP,
-				this.topK, this.thinking, this.toolCallbacks, this.toolNames, this.internalToolExecutionEnabled,
-				this.toolContext, this.httpHeaders, this.cacheOptions);
+				this.topK, this.toolChoice, this.thinking, this.toolCallbacks, this.toolNames,
+				this.internalToolExecutionEnabled, this.toolContext, this.httpHeaders, this.cacheOptions);
 	}
 
 	public static final class Builder {
@@ -351,6 +362,11 @@ public Builder topK(Integer topK) {
 			return this;
 		}
 
+		public Builder toolChoice(AnthropicApi.ToolChoice toolChoice) {
+			this.options.toolChoice = toolChoice;
+			return this;
+		}
+
 		public Builder thinking(ChatCompletionRequest.ThinkingConfig thinking) {
 			this.options.thinking = thinking;
 			return this;

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/api/AnthropicApi.java

@@ -512,6 +512,8 @@ public interface StreamEvent {
 	 * return tool_use content blocks that represent the model's use of those tools. You
 	 * can then run those tools using the tool input generated by the model and then
 	 * optionally return results back to the model using tool_result content blocks.
+	 * @param toolChoice How the model should use the provided tools. The model can use a
+	 * specific tool, any available tool, decide by itself, or not use tools at all.
 	 * @param thinking Configuration for the model's thinking mode. When enabled, the
 	 * model can perform more in-depth reasoning before responding to a query.
 	 */
@@ -529,17 +531,19 @@ public record ChatCompletionRequest(
 		@JsonProperty("top_p") Double topP,
 		@JsonProperty("top_k") Integer topK,
 		@JsonProperty("tools") List<Tool> tools,
+		@JsonProperty("tool_choice") ToolChoice toolChoice,
 		@JsonProperty("thinking") ThinkingConfig thinking) {
 		// @formatter:on
 
 		public ChatCompletionRequest(String model, List<AnthropicMessage> messages, Object system, Integer maxTokens,
 				Double temperature, Boolean stream) {
-			this(model, messages, system, maxTokens, null, null, stream, temperature, null, null, null, null);
+			this(model, messages, system, maxTokens, null, null, stream, temperature, null, null, null, null, null);
 		}
 
 		public ChatCompletionRequest(String model, List<AnthropicMessage> messages, Object system, Integer maxTokens,
 				List<String> stopSequences, Double temperature, Boolean stream) {
-			this(model, messages, system, maxTokens, null, stopSequences, stream, temperature, null, null, null, null);
+			this(model, messages, system, maxTokens, null, stopSequences, stream, temperature, null, null, null, null,
+					null);
 		}
 
 		public static ChatCompletionRequestBuilder builder() {
@@ -613,6 +617,8 @@ public static final class ChatCompletionRequestBuilder {
 
 		private List<Tool> tools;
 
+		private ToolChoice toolChoice;
+
 		private ChatCompletionRequest.ThinkingConfig thinking;
 
 		private ChatCompletionRequestBuilder() {
@@ -630,6 +636,7 @@ private ChatCompletionRequestBuilder(ChatCompletionRequest request) {
 			this.topP = request.topP;
 			this.topK = request.topK;
 			this.tools = request.tools;
+			this.toolChoice = request.toolChoice;
 			this.thinking = request.thinking;
 		}
 
@@ -693,6 +700,11 @@ public ChatCompletionRequestBuilder tools(List<Tool> tools) {
 			return this;
 		}
 
+		public ChatCompletionRequestBuilder toolChoice(ToolChoice toolChoice) {
+			this.toolChoice = toolChoice;
+			return this;
+		}
+
 		public ChatCompletionRequestBuilder thinking(ChatCompletionRequest.ThinkingConfig thinking) {
 			this.thinking = thinking;
 			return this;
@@ -705,7 +717,8 @@ public ChatCompletionRequestBuilder thinking(ThinkingType type, Integer budgetTo
 
 		public ChatCompletionRequest build() {
 			return new ChatCompletionRequest(this.model, this.messages, this.system, this.maxTokens, this.metadata,
-					this.stopSequences, this.stream, this.temperature, this.topP, this.topK, this.tools, this.thinking);
+					this.stopSequences, this.stream, this.temperature, this.topP, this.topK, this.tools,
+					this.toolChoice, this.thinking);
 		}
 
 	}
@@ -1135,6 +1148,126 @@ public Tool(String name, String description, Map<String, Object> inputSchema) {
 
 	}
 
+	/**
+	 * Base interface for tool choice options.
+	 */
+	@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.EXISTING_PROPERTY, property = "type",
+			visible = true)
+	@JsonSubTypes({ @JsonSubTypes.Type(value = ToolChoiceAuto.class, name = "auto"),
+			@JsonSubTypes.Type(value = ToolChoiceAny.class, name = "any"),
+			@JsonSubTypes.Type(value = ToolChoiceTool.class, name = "tool"),
+			@JsonSubTypes.Type(value = ToolChoiceNone.class, name = "none") })
+	public interface ToolChoice {
+
+		@JsonProperty("type")
+		String type();
+
+	}
+
+	/**
+	 * Auto tool choice - the model will automatically decide whether to use tools.
+	 *
+	 * @param type The type of tool choice, always "auto".
+	 * @param disableParallelToolUse Whether to disable parallel tool use. Defaults to
+	 * false. If set to true, the model will output at most one tool use.
+	 */
+	@JsonInclude(Include.NON_NULL)
+	public record ToolChoiceAuto(@JsonProperty("type") String type,
+			@JsonProperty("disable_parallel_tool_use") Boolean disableParallelToolUse) implements ToolChoice {
+
+		/**
+		 * Create an auto tool choice with default settings.
+		 */
+		public ToolChoiceAuto() {
+			this("auto", null);
+		}
+
+		/**
+		 * Create an auto tool choice with specific parallel tool use setting.
+		 * @param disableParallelToolUse Whether to disable parallel tool use.
+		 */
+		public ToolChoiceAuto(Boolean disableParallelToolUse) {
+			this("auto", disableParallelToolUse);
+		}
+
+	}
+
+	/**
+	 * Any tool choice - the model will use any available tools.
+	 *
+	 * @param type The type of tool choice, always "any".
+	 * @param disableParallelToolUse Whether to disable parallel tool use. Defaults to
+	 * false. If set to true, the model will output exactly one tool use.
+	 */
+	@JsonInclude(Include.NON_NULL)
+	public record ToolChoiceAny(@JsonProperty("type") String type,
+			@JsonProperty("disable_parallel_tool_use") Boolean disableParallelToolUse) implements ToolChoice {
+
+		/**
+		 * Create an any tool choice with default settings.
+		 */
+		public ToolChoiceAny() {
+			this("any", null);
+		}
+
+		/**
+		 * Create an any tool choice with specific parallel tool use setting.
+		 * @param disableParallelToolUse Whether to disable parallel tool use.
+		 */
+		public ToolChoiceAny(Boolean disableParallelToolUse) {
+			this("any", disableParallelToolUse);
+		}
+
+	}
+
+	/**
+	 * Tool choice - the model will use the specified tool.
+	 *
+	 * @param type The type of tool choice, always "tool".
+	 * @param name The name of the tool to use.
+	 * @param disableParallelToolUse Whether to disable parallel tool use. Defaults to
+	 * false. If set to true, the model will output exactly one tool use.
+	 */
+	@JsonInclude(Include.NON_NULL)
+	public record ToolChoiceTool(@JsonProperty("type") String type, @JsonProperty("name") String name,
+			@JsonProperty("disable_parallel_tool_use") Boolean disableParallelToolUse) implements ToolChoice {
+
+		/**
+		 * Create a tool choice for a specific tool.
+		 * @param name The name of the tool to use.
+		 */
+		public ToolChoiceTool(String name) {
+			this("tool", name, null);
+		}
+
+		/**
+		 * Create a tool choice for a specific tool with parallel tool use setting.
+		 * @param name The name of the tool to use.
+		 * @param disableParallelToolUse Whether to disable parallel tool use.
+		 */
+		public ToolChoiceTool(String name, Boolean disableParallelToolUse) {
+			this("tool", name, disableParallelToolUse);
+		}
+
+	}
+
+	/**
+	 * None tool choice - the model will not be allowed to use tools.
+	 *
+	 * @param type The type of tool choice, always "none".
+	 */
+	@JsonInclude(Include.NON_NULL)
+	public record ToolChoiceNone(@JsonProperty("type") String type) implements ToolChoice {
+
+		/**
+		 * Create a none tool choice.
+		 */
+		public ToolChoiceNone() {
+			this("none");
+		}
+
+	}
+
 	// CB START EVENT
 
 	/**