Add Function Calling Support for Anthropic Features

 - expanded the AnthropicApi to include Tool, facilitating request and response abstractions.
 - extended AnthropicChatClient to inherit AbstractFunctionCallSupport, with
   implementation of all necessary methods and function registration protocols.
 - implemented FunctionCallingOptions interface in AnthropicChatOptions.
 - added tools integration tests for AnthropoicApi and AnthropicChatClient.
 - extended the auto-configuration with functional calling functionality.
 - added ITs for tools auto-config.
 - updated documentation on anthropic function calling and relevant pages for comprehensive coverage.

Author: tzolov

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

@@ -17,8 +17,10 @@
 
 import java.util.ArrayList;
 import java.util.Base64;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.stream.Collectors;
 
@@ -28,13 +30,13 @@
 
 import org.springframework.ai.anthropic.api.AnthropicApi;
 import org.springframework.ai.anthropic.api.AnthropicApi.ChatCompletion;
-import org.springframework.ai.anthropic.api.AnthropicApi.RequestMessage;
-import org.springframework.ai.anthropic.api.AnthropicApi.MediaContent;
 import org.springframework.ai.anthropic.api.AnthropicApi.ChatCompletionRequest;
+import org.springframework.ai.anthropic.api.AnthropicApi.MediaContent;
+import org.springframework.ai.anthropic.api.AnthropicApi.MediaContent.Type;
+import org.springframework.ai.anthropic.api.AnthropicApi.RequestMessage;
 import org.springframework.ai.anthropic.api.AnthropicApi.Role;
 import org.springframework.ai.anthropic.api.AnthropicApi.StreamResponse;
 import org.springframework.ai.anthropic.api.AnthropicApi.Usage;
-import org.springframework.ai.anthropic.api.AnthropicApi.MediaContent.Type;
 import org.springframework.ai.anthropic.metadata.AnthropicChatResponseMetadata;
 import org.springframework.ai.chat.ChatClient;
 import org.springframework.ai.chat.ChatResponse;
@@ -45,6 +47,8 @@
 import org.springframework.ai.chat.prompt.ChatOptions;
 import org.springframework.ai.chat.prompt.Prompt;
 import org.springframework.ai.model.ModelOptionsUtils;
+import org.springframework.ai.model.function.AbstractFunctionCallSupport;
+import org.springframework.ai.model.function.FunctionCallbackContext;
 import org.springframework.ai.retry.RetryUtils;
 import org.springframework.http.ResponseEntity;
 import org.springframework.retry.support.RetryTemplate;
@@ -57,7 +61,9 @@
  * @author Christian Tzolov
  * @since 1.0.0
  */
-public class AnthropicChatClient implements ChatClient, StreamingChatClient {
+public class AnthropicChatClient extends
+		AbstractFunctionCallSupport<AnthropicApi.RequestMessage, AnthropicApi.ChatCompletionRequest, ResponseEntity<AnthropicApi.ChatCompletion>>
+		implements ChatClient, StreamingChatClient {
 
 	private static final Logger logger = LoggerFactory.getLogger(AnthropicChatClient.class);
 
@@ -112,6 +118,22 @@ public AnthropicChatClient(AnthropicApi anthropicApi, AnthropicChatOptions defau
 	 */
 	public AnthropicChatClient(AnthropicApi anthropicApi, AnthropicChatOptions defaultOptions,
 			RetryTemplate retryTemplate) {
+		this(anthropicApi, defaultOptions, retryTemplate, null);
+	}
+
+	/**
+	 * Construct a new {@link AnthropicChatClient} instance.
+	 * @param anthropicApi the lower-level API for the Anthropic service.
+	 * @param defaultOptions the default options used for the chat completion requests.
+	 * @param retryTemplate the retry template used to retry the Anthropic API calls.
+	 * @param functionCallbackContext the function callback context used to store the
+	 * state of the function calls.
+	 */
+	public AnthropicChatClient(AnthropicApi anthropicApi, AnthropicChatOptions defaultOptions,
+			RetryTemplate retryTemplate, FunctionCallbackContext functionCallbackContext) {
+
+		super(functionCallbackContext);
+
 		Assert.notNull(anthropicApi, "AnthropicApi must not be null");
 		Assert.notNull(defaultOptions, "DefaultOptions must not be null");
 		Assert.notNull(retryTemplate, "RetryTemplate must not be null");
@@ -127,7 +149,7 @@ public ChatResponse call(Prompt prompt) {
 		ChatCompletionRequest request = createRequest(prompt, false);
 
 		return this.retryTemplate.execute(ctx -> {
-			ResponseEntity<ChatCompletion> completionEntity = this.anthropicApi.chatCompletionEntity(request);
+			ResponseEntity<ChatCompletion> completionEntity = this.callWithFunctionSupport(request);
 			return toChatResponse(completionEntity.getBody());
 		});
 	}
@@ -229,6 +251,8 @@ else if (mediaData instanceof String text) {
 
 	ChatCompletionRequest createRequest(Prompt prompt, boolean stream) {
 
+		Set<String> functionsForThisRequest = new HashSet<>();
+
 		List<RequestMessage> userMessages = prompt.getInstructions()
 			.stream()
 			.filter(m -> m.getMessageType() != MessageType.SYSTEM)
@@ -260,6 +284,10 @@ ChatCompletionRequest createRequest(Prompt prompt, boolean stream) {
 				AnthropicChatOptions updatedRuntimeOptions = ModelOptionsUtils.copyToTarget(runtimeOptions,
 						ChatOptions.class, AnthropicChatOptions.class);
 
+				Set<String> promptEnabledFunctions = this.handleFunctionCallbackConfigurations(updatedRuntimeOptions,
+						IS_RUNTIME_CALL);
+				functionsForThisRequest.addAll(promptEnabledFunctions);
+
 				request = ModelOptionsUtils.merge(updatedRuntimeOptions, request, ChatCompletionRequest.class);
 			}
 			else {
@@ -269,12 +297,32 @@ ChatCompletionRequest createRequest(Prompt prompt, boolean stream) {
 		}
 
 		if (this.defaultOptions != null) {
+			Set<String> defaultEnabledFunctions = this.handleFunctionCallbackConfigurations(this.defaultOptions,
+					!IS_RUNTIME_CALL);
+			functionsForThisRequest.addAll(defaultEnabledFunctions);
+
 			request = ModelOptionsUtils.merge(request, this.defaultOptions, ChatCompletionRequest.class);
 		}
 
+		if (!CollectionUtils.isEmpty(functionsForThisRequest)) {
+
+			List<AnthropicApi.Tool> tools = getFunctionTools(functionsForThisRequest);
+
+			request = ChatCompletionRequest.from(request).withTools(tools).build();
+		}
+
 		return request;
 	}
 
+	private List<AnthropicApi.Tool> getFunctionTools(Set<String> functionNames) {
+		return this.resolveFunctionCallbacks(functionNames).stream().map(functionCallback -> {
+			var description = functionCallback.getDescription();
+			var name = functionCallback.getName();
+			String inputSchema = functionCallback.getInputTypeSchema();
+			return new AnthropicApi.Tool(name, description, ModelOptionsUtils.jsonToMap(inputSchema));
+		}).toList();
+	}
+
 	private static class ChatCompletionBuilder {
 
 		private String type;
@@ -343,4 +391,63 @@ public ChatCompletion build() {
 
 	}
 
+	@Override
+	protected ChatCompletionRequest doCreateToolResponseRequest(ChatCompletionRequest previousRequest,
+			RequestMessage responseMessage, List<RequestMessage> conversationHistory) {
+
+		List<MediaContent> toolToUseList = responseMessage.content()
+			.stream()
+			.filter(c -> c.type() == MediaContent.Type.TOOL_USE)
+			.toList();
+
+		List<MediaContent> toolResults = new ArrayList<>();
+
+		for (MediaContent toolToUse : toolToUseList) {
+
+			var functionCallId = toolToUse.id();
+			var functionName = toolToUse.name();
+			var functionArguments = toolToUse.input();
+
+			if (!this.functionCallbackRegister.containsKey(functionName)) {
+				throw new IllegalStateException("No function callback found for function name: " + functionName);
+			}
+
+			String functionResponse = this.functionCallbackRegister.get(functionName)
+				.call(ModelOptionsUtils.toJsonString(functionArguments));
+
+			toolResults.add(new MediaContent(Type.TOOL_RESULT, functionCallId, functionResponse));
+		}
+
+		// Add the function response to the conversation.
+		conversationHistory.add(new RequestMessage(toolResults, Role.USER));
+
+		// Recursively call chatCompletionWithTools until the model doesn't call a
+		// functions anymore.
+		return ChatCompletionRequest.from(previousRequest).withMessages(conversationHistory).build();
+	}
+
+	@Override
+	protected List<RequestMessage> doGetUserMessages(ChatCompletionRequest request) {
+		return request.messages();
+	}
+
+	@Override
+	protected RequestMessage doGetToolResponseMessage(ResponseEntity<ChatCompletion> response) {
+		return new RequestMessage(response.getBody().content(), Role.ASSISTANT);
+	}
+
+	@Override
+	protected ResponseEntity<ChatCompletion> doChatCompletion(ChatCompletionRequest request) {
+		return this.anthropicApi.chatCompletionEntity(request);
+	}
+
+	@SuppressWarnings("null")
+	@Override
+	protected boolean isToolFunctionCall(ResponseEntity<ChatCompletion> response) {
+		if (response == null || response.getBody() == null || CollectionUtils.isEmpty(response.getBody().content())) {
+			return false;
+		}
+		return response.getBody().content().stream().anyMatch(content -> content.type() == MediaContent.Type.TOOL_USE);
+	}
+
 }

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

@@ -15,14 +15,22 @@
  */
 package org.springframework.ai.anthropic;
 
+import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Set;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import org.springframework.ai.anthropic.api.AnthropicApi.ChatCompletionRequest;
 import org.springframework.ai.chat.prompt.ChatOptions;
+import org.springframework.ai.model.function.FunctionCallback;
+import org.springframework.ai.model.function.FunctionCallingOptions;
+import org.springframework.boot.context.properties.NestedConfigurationProperty;
+import org.springframework.util.Assert;
 
 /**
  * The options to be used when sending a chat request to the Anthropic API.
@@ -31,7 +39,7 @@
  * @since 1.0.0
  */
 @JsonInclude(Include.NON_NULL)
-public class AnthropicChatOptions implements ChatOptions {
+public class AnthropicChatOptions implements ChatOptions, FunctionCallingOptions {
 
 	// @formatter:off
 	private @JsonProperty("model") String model;
@@ -41,6 +49,32 @@ public class AnthropicChatOptions implements ChatOptions {
 	private @JsonProperty("temperature") Float temperature;
 	private @JsonProperty("top_p") Float topP;
 	private @JsonProperty("top_k") Integer topK;
+
+	/**
+	 * Tool Function Callbacks to register with the ChatClient. For Prompt
+	 * Options the functionCallbacks are automatically enabled for the duration of the
+	 * prompt execution. For Default Options the functionCallbacks are registered but
+	 * disabled by default. Use the enableFunctions to set the functions from the registry
+	 * to be used by the ChatClient chat completion requests.
+	 */
+	@NestedConfigurationProperty
+	@JsonIgnore
+	private List<FunctionCallback> functionCallbacks = new ArrayList<>();
+
+	/**
+	 * List of functions, identified by their names, to configure for function calling in
+	 * the chat completion requests. Functions with those names must exist in the
+	 * functionCallbacks registry. The {@link #functionCallbacks} from the PromptOptions
+	 * are automatically enabled for the duration of the prompt execution.
+	 *
+	 * Note that function enabled with the default options are enabled for all chat
+	 * completion requests. This could impact the token count and the billing. If the
+	 * functions is set in a prompt options, then the enabled functions are only active
+	 * for the duration of this prompt execution.
+	 */
+	@NestedConfigurationProperty
+	@JsonIgnore
+	private Set<String> functions = new HashSet<>();
 	// @formatter:on
 
 	public static Builder builder() {
@@ -86,6 +120,23 @@ public Builder withTopK(Integer topK) {
 			return this;
 		}
 
+		public Builder withFunctionCallbacks(List<FunctionCallback> functionCallbacks) {
+			this.options.functionCallbacks = functionCallbacks;
+			return this;
+		}
+
+		public Builder withFunctions(Set<String> functionNames) {
+			Assert.notNull(functionNames, "Function names must not be null");
+			this.options.functions = functionNames;
+			return this;
+		}
+
+		public Builder withFunction(String functionName) {
+			Assert.hasText(functionName, "Function name must not be empty");
+			this.options.functions.add(functionName);
+			return this;
+		}
+
 		public AnthropicChatOptions build() {
 			return this.options;
 		}
@@ -150,4 +201,26 @@ public void setTopK(Integer topK) {
 		this.topK = topK;
 	}
 
+	@Override
+	public List<FunctionCallback> getFunctionCallbacks() {
+		return this.functionCallbacks;
+	}
+
+	@Override
+	public void setFunctionCallbacks(List<FunctionCallback> functionCallbacks) {
+		Assert.notNull(functionCallbacks, "FunctionCallbacks must not be null");
+		this.functionCallbacks = functionCallbacks;
+	}
+
+	@Override
+	public Set<String> getFunctions() {
+		return this.functions;
+	}
+
+	@Override
+	public void setFunctions(Set<String> functions) {
+		Assert.notNull(functions, "Function must not be null");
+		this.functions = functions;
+	}
+
 }