Spring AI 源码解析：Tool Calling链路调用流程及示例

public class DefaultChatClient implements ChatClient {
    @Override
    public ChatClientRequestSpec tools(String... toolNames) {
        Assert.notNull(toolNames, "toolNames cannot be null");
        Assert.noNullElements(toolNames, "toolNames cannot contain null elements");
        this.functionNames.addAll(List.of(toolNames));
        return this;
    }

    @Override
    public ChatClientRequestSpec tools(FunctionCallback... toolCallbacks) {
        Assert.notNull(toolCallbacks, "toolCallbacks cannot be null");
        Assert.noNullElements(toolCallbacks, "toolCallbacks cannot contain null elements");
        this.functionCallbacks.addAll(List.of(toolCallbacks));
        return this;
    }

    @Override
    public ChatClientRequestSpec tools(List<ToolCallback> toolCallbacks) {
        Assert.notNull(toolCallbacks, "toolCallbacks cannot be null");
        Assert.noNullElements(toolCallbacks, "toolCallbacks cannot contain null elements");
        this.functionCallbacks.addAll(toolCallbacks);
        return this;
    }

    @Override
    public ChatClientRequestSpec tools(Object... toolObjects) {
        Assert.notNull(toolObjects, "toolObjects cannot be null");
        Assert.noNullElements(toolObjects, "toolObjects cannot contain null elements");
        this.functionCallbacks.addAll(Arrays.asList(ToolCallbacks.from(toolObjects)));
        return this;
    }

    @Override
    public ChatClientRequestSpec tools(ToolCallbackProvider... toolCallbackProviders) {
        Assert.notNull(toolCallbackProviders, "toolCallbackProviders cannot be null");
        Assert.noNullElements(toolCallbackProviders, "toolCallbackProviders cannot contain null elements");
        for (ToolCallbackProvider toolCallbackProvider : toolCallbackProviders) {
           this.functionCallbacks.addAll(List.of(toolCallbackProvider.getToolCallbacks()));
        }
        return this;
    }

}

@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Tool {

    /**
     * The name of the tool. If not provided, the method name will be used.
     */
    String name() default "";

    /**
     * The description of the tool. If not provided, the method name will be used.
     */
    String description() default "";

    /**
     * Whether the tool result should be returned directly or passed back to the model.
     */
    boolean returnDirect() default false;

    /**
     * The class to use to convert the tool call result to a String.
     */
    Class<? extends ToolCallResultConverter> resultConverter() default DefaultToolCallResultConverter.class;

}

public interface ToolDefinition {
    // 工具的名称，提供给一个模型时要求唯一标识
    String name();
    // 工具描述
    String description();
    // 工具的输入模式
    String inputSchema();

    static DefaultToolDefinition.Builder builder() {
       return DefaultToolDefinition.builder();
    }
    // 从方法中提取出工具的名称、描述、输入模式
    static DefaultToolDefinition.Builder builder(Method method) {
       Assert.notNull(method, "method cannot be null");
       return DefaultToolDefinition.builder()
          .name(ToolUtils.getToolName(method))
          .description(ToolUtils.getToolDescription(method))
          .inputSchema(JsonSchemaGenerator.generateForMethodInput(method));
    }

    static ToolDefinition from(Method method) {
       return ToolDefinition.builder(method).build();
    }

}

public record DefaultToolDefinition(String name, String description, String inputSchema) implements ToolDefinition {

    public DefaultToolDefinition {
       Assert.hasText(name, "name cannot be null or empty");
       Assert.hasText(description, "description cannot be null or empty");
       Assert.hasText(inputSchema, "inputSchema cannot be null or empty");
    }

    public static Builder builder() {
       return new Builder();
    }

    public static class Builder {

       private String name;

       private String description;

       private String inputSchema;

       private Builder() {
       }

       public Builder name(String name) {
          this.name = name;
          return this;
       }

       public Builder description(String description) {
          this.description = description;
          return this;
       }

       public Builder inputSchema(String inputSchema) {
          this.inputSchema = inputSchema;
          return this;
       }

       public ToolDefinition build() {
          if (!StringUtils.hasText(description)) {
             description = ToolUtils.getToolDescriptionFromName(name);
          }
          return new DefaultToolDefinition(name, description, inputSchema);
       }

    }

}

public interface ToolMetadata {

    default boolean returnDirect() {
       return false;
    }

    static DefaultToolMetadata.Builder builder() {
       return DefaultToolMetadata.builder();
    }

    static ToolMetadata from(Method method) {
       Assert.notNull(method, "method cannot be null");
       return DefaultToolMetadata.builder().returnDirect(ToolUtils.getToolReturnDirect(method)).build();
    }

}

public record DefaultToolMetadata(boolean returnDirect) implements ToolMetadata {

    public static Builder builder() {
       return new Builder();
    }

    public static class Builder {

       private boolean returnDirect = false;

       private Builder() {
       }

       public Builder returnDirect(boolean returnDirect) {
          this.returnDirect = returnDirect;
          return this;
       }

       public ToolMetadata build() {
          return new DefaultToolMetadata(returnDirect);
       }

    }

}

public interface ToolCallback{

    // AI模型用来确定何时以及如何调用工具的定义
    ToolDefinition getToolDefinition();

    // 元数据提供了额外的信息怎么操作工具
    default ToolMetadata getToolMetadata() {
       return ToolMetadata.builder().build();
    }

    // toolInput为工具的输入，最终返回结果工具的结果
    String call(String toolInput);

    // toolInput为工具的输入，tooContext为工具的上下文信息
    default String call(String toolInput, @Nullable ToolContext tooContext) {
       if (tooContext != null && !tooContext.getContext().isEmpty()) {
          throw new UnsupportedOperationException("Tool context is not supported!");
       }
       return call(toolInput);
    }

}

public class MethodToolCallback implements ToolCallback {

    private static final Logger logger = LoggerFactory.getLogger(MethodToolCallback.class);

    private static final ToolCallResultConverter DEFAULT_RESULT_CONVERTER = new DefaultToolCallResultConverter();

    private static final ToolMetadata DEFAULT_TOOL_METADATA = ToolMetadata.builder().build();

    private final ToolDefinition toolDefinition;

    private final ToolMetadata toolMetadata;

    private final Method toolMethod;

    @Nullable
    private final Object toolObject;

    private final ToolCallResultConverter toolCallResultConverter;

    public MethodToolCallback(ToolDefinition toolDefinition, @Nullable ToolMetadata toolMetadata, Method toolMethod,
          @Nullable Object toolObject, @Nullable ToolCallResultConverter toolCallResultConverter) {
       Assert.notNull(toolDefinition, "toolDefinition cannot be null");
       Assert.notNull(toolMethod, "toolMethod cannot be null");
       Assert.isTrue(Modifier.isStatic(toolMethod.getModifiers()) || toolObject != null,
             "toolObject cannot be null for non-static methods");
       this.toolDefinition = toolDefinition;
       this.toolMetadata = toolMetadata != null ? toolMetadata : DEFAULT_TOOL_METADATA;
       this.toolMethod = toolMethod;
       this.toolObject = toolObject;
       this.toolCallResultConverter = toolCallResultConverter != null ? toolCallResultConverter
             : DEFAULT_RESULT_CONVERTER;
    }

    @Override
    public ToolDefinition getToolDefinition() {
       return toolDefinition;
    }

    @Override
    public ToolMetadata getToolMetadata() {
       return toolMetadata;
    }

    @Override
    public String call(String toolInput) {
       return call(toolInput, null);
    }

    @Override
    public String call(String toolInput, @Nullable ToolContext toolContext) {
       Assert.hasText(toolInput, "toolInput cannot be null or empty");

       logger.debug("Starting execution of tool: {}", toolDefinition.name());

       validateToolContextSupport(toolContext);

       Map<String, Object> toolArguments = extractToolArguments(toolInput);

       Object[] methodArguments = buildMethodArguments(toolArguments, toolContext);

       Object result = callMethod(methodArguments);

       logger.debug("Successful execution of tool: {}", toolDefinition.name());

       Type returnType = toolMethod.getGenericReturnType();

       return toolCallResultConverter.convert(result, returnType);
    }

    private void validateToolContextSupport(@Nullable ToolContext toolContext) {
       var isNonEmptyToolContextProvided = toolContext != null && !CollectionUtils.isEmpty(toolContext.getContext());
       var isToolContextAcceptedByMethod = Stream.of(toolMethod.getParameterTypes())
          .anyMatch(type -> ClassUtils.isAssignable(type, ToolContext.class));
       if (isToolContextAcceptedByMethod && !isNonEmptyToolContextProvided) {
          throw new IllegalArgumentException("ToolContext is required by the method as an argument");
       }
    }

    private Map<String, Object> extractToolArguments(String toolInput) {
       return JsonParser.fromJson(toolInput, new TypeReference<>() {
       });
    }

    // Based on the implementation in MethodInvokingFunctionCallback.
    private Object[] buildMethodArguments(Map<String, Object> toolInputArguments, @Nullable ToolContext toolContext) {
       return Stream.of(toolMethod.getParameters()).map(parameter -> {
          if (parameter.getType().isAssignableFrom(ToolContext.class)) {
             return toolContext;
          }
          Object rawArgument = toolInputArguments.get(parameter.getName());
          return buildTypedArgument(rawArgument, parameter.getType());
       }).toArray();
    }

    @Nullable
    private Object buildTypedArgument(@Nullable Object value, Class<?> type) {
       if (value == null) {
          return null;
       }
       return JsonParser.toTypedObject(value, type);
    }

    @Nullable
    private Object callMethod(Object[] methodArguments) {
       if (isObjectNotPublic() || isMethodNotPublic()) {
          toolMethod.setAccessible(true);
       }

       Object result;
       try {
          result = toolMethod.invoke(toolObject, methodArguments);
       }
       catch (IllegalAccessException ex) {
          throw new IllegalStateException("Could not access method: " + ex.getMessage(), ex);
       }
       catch (InvocationTargetException ex) {
          throw new ToolExecutionException(toolDefinition, ex.getCause());
       }
       return result;
    }

    private boolean isObjectNotPublic() {
       return toolObject != null && !Modifier.isPublic(toolObject.getClass().getModifiers());
    }

    private boolean isMethodNotPublic() {
       return !Modifier.isPublic(toolMethod.getModifiers());
    }

    @Override
    public String toString() {
       return "MethodToolCallback{" + "toolDefinition=" + toolDefinition + ", toolMetadata=" + toolMetadata + '}';
    }

    public static Builder builder() {
       return new Builder();
    }

    public static class Builder {

       private ToolDefinition toolDefinition;

       private ToolMetadata toolMetadata;

       private Method toolMethod;

       private Object toolObject;

       private ToolCallResultConverter toolCallResultConverter;

       private Builder() {
       }

       public Builder toolDefinition(ToolDefinition toolDefinition) {
          this.toolDefinition = toolDefinition;
          return this;
       }

       public Builder toolMetadata(ToolMetadata toolMetadata) {
          this.toolMetadata = toolMetadata;
          return this;
       }

       public Builder toolMethod(Method toolMethod) {
          this.toolMethod = toolMethod;
          return this;
       }

       public Builder toolObject(Object toolObject) {
          this.toolObject = toolObject;
          return this;
       }

       public Builder toolCallResultConverter(ToolCallResultConverter toolCallResultConverter) {
          this.toolCallResultConverter = toolCallResultConverter;
          return this;
       }

       public MethodToolCallback build() {
          return new MethodToolCallback(toolDefinition, toolMetadata, toolMethod, toolObject,
                toolCallResultConverter);
       }

    }

}

I request = JsonParser.fromJson(toolInput, toolInputType);

O response = toolFunction.apply(request, toolContext);
public class FunctionToolCallback<I, O> implements ToolCallback {

    private static final Logger logger = LoggerFactory.getLogger(FunctionToolCallback.class);

    private static final ToolCallResultConverter DEFAULT_RESULT_CONVERTER = new DefaultToolCallResultConverter();

    private static final ToolMetadata DEFAULT_TOOL_METADATA = ToolMetadata.builder().build();

    private final ToolDefinition toolDefinition;

    private final ToolMetadata toolMetadata;

    private final Type toolInputType;

    private final BiFunction<I, ToolContext, O> toolFunction;

    private final ToolCallResultConverter toolCallResultConverter;

    public FunctionToolCallback(ToolDefinition toolDefinition, @Nullable ToolMetadata toolMetadata, Type toolInputType,
          BiFunction<I, ToolContext, O> toolFunction, @Nullable ToolCallResultConverter toolCallResultConverter) {
       Assert.notNull(toolDefinition, "toolDefinition cannot be null");
       Assert.notNull(toolInputType, "toolInputType cannot be null");
       Assert.notNull(toolFunction, "toolFunction cannot be null");
       this.toolDefinition = toolDefinition;
       this.toolMetadata = toolMetadata != null ? toolMetadata : DEFAULT_TOOL_METADATA;
       this.toolFunction = toolFunction;
       this.toolInputType = toolInputType;
       this.toolCallResultConverter = toolCallResultConverter != null ? toolCallResultConverter
             : DEFAULT_RESULT_CONVERTER;
    }

    @Override
    public ToolDefinition getToolDefinition() {
       return toolDefinition;
    }

    @Override
    public ToolMetadata getToolMetadata() {
       return toolMetadata;
    }

    @Override
    public String call(String toolInput) {
       return call(toolInput, null);
    }

    @Override
    public String call(String toolInput, @Nullable ToolContext toolContext) {
       Assert.hasText(toolInput, "toolInput cannot be null or empty");

       logger.debug("Starting execution of tool: {}", toolDefinition.name());

       I request = JsonParser.fromJson(toolInput, toolInputType);
       O response = toolFunction.apply(request, toolContext);

       logger.debug("Successful execution of tool: {}", toolDefinition.name());

       return toolCallResultConverter.convert(response, null);
    }

    @Override
    public String toString() {
       return "FunctionToolCallback{" + "toolDefinition=" + toolDefinition + ", toolMetadata=" + toolMetadata + '}';
    }


    public static <I, O> Builder<I, O> builder(String name, BiFunction<I, ToolContext, O> function) {
       return new Builder<>(name, function);
    }


    public static <I, O> Builder<I, O> builder(String name, Function<I, O> function) {
       Assert.notNull(function, "function cannot be null");
       return new Builder<>(name, (request, context) -> function.apply(request));
    }


    public static <O> Builder<Void, O> builder(String name, Supplier<O> supplier) {
       Assert.notNull(supplier, "supplier cannot be null");
       Function<Void, O> function = input -> supplier.get();
       return builder(name, function).inputType(Void.class);
    }


    public static <I> Builder<I, Void> builder(String name, Consumer<I> consumer) {
       Assert.notNull(consumer, "consumer cannot be null");
       Function<I, Void> function = (I input) -> {
          consumer.accept(input);
          return null;
       };
       return builder(name, function);
    }

    public static class Builder<I, O> {

       private String name;

       private String description;

       private String inputSchema;

       private Type inputType;

       private ToolMetadata toolMetadata;

       private BiFunction<I, ToolContext, O> toolFunction;

       private ToolCallResultConverter toolCallResultConverter;

       private Builder(String name, BiFunction<I, ToolContext, O> toolFunction) {
          Assert.hasText(name, "name cannot be null or empty");
          Assert.notNull(toolFunction, "toolFunction cannot be null");
          this.name = name;
          this.toolFunction = toolFunction;
       }

       public Builder<I, O> description(String description) {
          this.description = description;
          return this;
       }

       public Builder<I, O> inputSchema(String inputSchema) {
          this.inputSchema = inputSchema;
          return this;
       }

       public Builder<I, O> inputType(Type inputType) {
          this.inputType = inputType;
          return this;
       }

       public Builder<I, O> inputType(ParameterizedTypeReference<?> inputType) {
          Assert.notNull(inputType, "inputType cannot be null");
          this.inputType = inputType.getType();
          return this;
       }

       public Builder<I, O> toolMetadata(ToolMetadata toolMetadata) {
          this.toolMetadata = toolMetadata;
          return this;
       }

       public Builder<I, O> toolCallResultConverter(ToolCallResultConverter toolCallResultConverter) {
          this.toolCallResultConverter = toolCallResultConverter;
          return this;
       }

       public FunctionToolCallback<I, O> build() {
          Assert.notNull(inputType, "inputType cannot be null");
          var toolDefinition = ToolDefinition.builder()
             .name(name)
             .description(
                   StringUtils.hasText(description) ? description : ToolUtils.getToolDescriptionFromName(name))
             .inputSchema(
                   StringUtils.hasText(inputSchema) ? inputSchema : JsonSchemaGenerator.generateForType(inputType))
             .build();
          return new FunctionToolCallback<>(toolDefinition, toolMetadata, inputType, toolFunction,
                toolCallResultConverter);
       }

    }

}

public interface ToolCallbackProvider {

    ToolCallback[] getToolCallbacks();

    static ToolCallbackProvider from(List<? extends FunctionCallback> toolCallbacks) {
       return new StaticToolCallbackProvider(toolCallbacks);
    }

    static ToolCallbackProvider from(FunctionCallback... toolCallbacks) {
       return new StaticToolCallbackProvider(toolCallbacks);
    }

}

public class MethodToolCallbackProvider implements ToolCallbackProvider {

    private static final Logger logger = LoggerFactory.getLogger(MethodToolCallbackProvider.class);

    private final List<Object> toolObjects;

    private MethodToolCallbackProvider(List<Object> toolObjects) {
       Assert.notNull(toolObjects, "toolObjects cannot be null");
       Assert.noNullElements(toolObjects, "toolObjects cannot contain null elements");
       this.toolObjects = toolObjects;
    }

    @Override
    public ToolCallback[] getToolCallbacks() {
       var toolCallbacks = toolObjects.stream()
          .map(toolObject -> Stream
             .of(ReflectionUtils.getDeclaredMethods(
                   AopUtils.isAopProxy(toolObject) ? AopUtils.getTargetClass(toolObject) : toolObject.getClass()))
             .filter(toolMethod -> toolMethod.isAnnotationPresent(Tool.class))
             .filter(toolMethod -> !isFunctionalType(toolMethod))
             .map(toolMethod -> MethodToolCallback.builder()
                .toolDefinition(ToolDefinition.from(toolMethod))
                .toolMetadata(ToolMetadata.from(toolMethod))
                .toolMethod(toolMethod)
                .toolObject(toolObject)
                .toolCallResultConverter(ToolUtils.getToolCallResultConverter(toolMethod))
                .build())
             .toArray(ToolCallback[]::new))
          .flatMap(Stream::of)
          .toArray(ToolCallback[]::new);

       validateToolCallbacks(toolCallbacks);

       return toolCallbacks;
    }

    private boolean isFunctionalType(Method toolMethod) {
       var isFunction = ClassUtils.isAssignable(toolMethod.getReturnType(), Function.class)
             || ClassUtils.isAssignable(toolMethod.getReturnType(), Supplier.class)
             || ClassUtils.isAssignable(toolMethod.getReturnType(), Consumer.class);

       if (isFunction) {
          logger.warn("Method {} is annotated with @Tool but returns a functional type. "
                + "This is not supported and the method will be ignored.", toolMethod.getName());
       }

       return isFunction;
    }

    private void validateToolCallbacks(ToolCallback[] toolCallbacks) {
       List<String> duplicateToolNames = ToolUtils.getDuplicateToolNames(toolCallbacks);
       if (!duplicateToolNames.isEmpty()) {
          throw new IllegalStateException("Multiple tools with the same name (%s) found in sources: %s".formatted(
                String.join(", ", duplicateToolNames),
                toolObjects.stream().map(o -> o.getClass().getName()).collect(Collectors.joining(", "))));
       }
    }

    public static Builder builder() {
       return new Builder();
    }

    public static class Builder {

       private List<Object> toolObjects;

       private Builder() {
       }

       public Builder toolObjects(Object... toolObjects) {
          Assert.notNull(toolObjects, "toolObjects cannot be null");
          this.toolObjects = Arrays.asList(toolObjects);
          return this;
       }

       public MethodToolCallbackProvider build() {
          return new MethodToolCallbackProvider(toolObjects);
       }

    }

}

public class StaticToolCallbackProvider implements ToolCallbackProvider {

    private final FunctionCallback[] toolCallbacks;

    public StaticToolCallbackProvider(FunctionCallback... toolCallbacks) {
       Assert.notNull(toolCallbacks, "ToolCallbacks must not be null");
       this.toolCallbacks = toolCallbacks;
    }

    public StaticToolCallbackProvider(List<? extends FunctionCallback> toolCallbacks) {
       Assert.noNullElements(toolCallbacks, "toolCallbacks cannot contain null elements");
       this.toolCallbacks = toolCallbacks.toArray(new FunctionCallback[0]);
    }

    @Override
    public FunctionCallback[] getToolCallbacks() {
       return this.toolCallbacks;
    }

}

public interface ToolCallingManager {

     // 从配置中提取工具的定义，确保模型能正确识别和使用工具
    List<ToolDefinition> resolveToolDefinitions(ToolCallingChatOptions chatOptions);

    // 根据模型的响应，执行响应的工具调用，并返回执行结果
    ToolExecutionResult executeToolCalls(Prompt prompt, ChatResponse chatResponse);

    // 构建工具调用管理器
    static DefaultToolCallingManager.Builder builder() {
       return DefaultToolCallingManager.builder();
    }

}

public class DefaultToolCallingManager implements ToolCallingManager {

    @Override
    public List<ToolDefinition> resolveToolDefinitions(ToolCallingChatOptions chatOptions) {
        Assert.notNull(chatOptions, "chatOptions cannot be null");

        List<FunctionCallback> toolCallbacks = new ArrayList<>(chatOptions.getToolCallbacks());
        for (String toolName : chatOptions.getToolNames()) {
           // Skip the tool if it is already present in the request toolCallbacks.
           // That might happen if a tool is defined in the options
           // both as a ToolCallback and as a tool name.
           if (chatOptions.getToolCallbacks().stream().anyMatch(tool -> tool.getName().equals(toolName))) {
              continue;
           }
           FunctionCallback toolCallback = toolCallbackResolver.resolve(toolName);
           if (toolCallback == null) {
              throw new IllegalStateException("No ToolCallback found for tool name: " + toolName);
           }
           toolCallbacks.add(toolCallback);
        }

        return toolCallbacks.stream().map(functionCallback -> {
           if (functionCallback instanceof ToolCallback toolCallback) {
              return toolCallback.getToolDefinition();
           }
           else {
              return ToolDefinition.builder()
                 .name(functionCallback.getName())
                 .description(functionCallback.getDescription())
                 .inputSchema(functionCallback.getInputTypeSchema())
                 .build();
           }
        }).toList();
    }

    @Override
    public ToolExecutionResult executeToolCalls(Prompt prompt, ChatResponse chatResponse) {
        Assert.notNull(prompt, "prompt cannot be null");
        Assert.notNull(chatResponse, "chatResponse cannot be null");

        Optional<Generation> toolCallGeneration = chatResponse.getResults()
           .stream()
           .filter(g -> !CollectionUtils.isEmpty(g.getOutput().getToolCalls()))
           .findFirst();

        if (toolCallGeneration.isEmpty()) {
           throw new IllegalStateException("No tool call requested by the chat model");
        }

        AssistantMessage assistantMessage = toolCallGeneration.get().getOutput();

        ToolContext toolContext = buildToolContext(prompt, assistantMessage);

        InternalToolExecutionResult internalToolExecutionResult = executeToolCall(prompt, assistantMessage,
              toolContext);

        List<Message> conversationHistory = buildConversationHistoryAfterToolExecution(prompt.getInstructions(),
              assistantMessage, internalToolExecutionResult.toolResponseMessage());

        return ToolExecutionResult.builder()
           .conversationHistory(conversationHistory)
           .returnDirect(internalToolExecutionResult.returnDirect())
           .build();
    }

}

@FunctionalInterface
public interface ToolCallResultConverter {

    // result：工具结果，returnType：返回类型
    String convert(@Nullable Object result, @Nullable Type returnType);

}

public final class DefaultToolCallResultConverter implements ToolCallResultConverter {

    private static final Logger logger = LoggerFactory.getLogger(DefaultToolCallResultConverter.class);

    @Override
    public String convert(@Nullable Object result, @Nullable Type returnType) {
       if (returnType == Void.TYPE) {
          logger.debug("The tool has no return type. Converting to conventional response.");
          return "Done";
       }
       else {
          logger.debug("Converting tool result to JSON.");
          return JsonParser.toJson(result);
       }
    }

}

public class ToolContext {

    public static final String TOOL_CALL_HISTORY = "TOOL_CALL_HISTORY";

    private final Map<String, Object> context;

    public ToolContext(Map<String, Object> context) {
       this.context = Collections.unmodifiableMap(context);
    }

    public Map<String, Object> getContext() {
       return this.context;
    }

    @SuppressWarnings("unchecked")
    public List<Message> getToolCallHistory() {
       return (List<Message>) this.context.get(TOOL_CALL_HISTORY);
    }

}

public final class ToolUtils {

    private ToolUtils() {
    }

    public static String getToolName(Method method) {
       Assert.notNull(method, "method cannot be null");
       var tool = method.getAnnotation(Tool.class);
       if (tool == null) {
          return method.getName();
       }
       return StringUtils.hasText(tool.name()) ? tool.name() : method.getName();
    }

    public static String getToolDescriptionFromName(String toolName) {
       Assert.hasText(toolName, "toolName cannot be null or empty");
       return ParsingUtils.reConcatenateCamelCase(toolName, " ");
    }

    public static String getToolDescription(Method method) {
       Assert.notNull(method, "method cannot be null");
       var tool = method.getAnnotation(Tool.class);
       if (tool == null) {
          return ParsingUtils.reConcatenateCamelCase(method.getName(), " ");
       }
       return StringUtils.hasText(tool.description()) ? tool.description() : method.getName();
    }

    public static boolean getToolReturnDirect(Method method) {
       Assert.notNull(method, "method cannot be null");
       var tool = method.getAnnotation(Tool.class);
       return tool != null && tool.returnDirect();
    }

    public static ToolCallResultConverter getToolCallResultConverter(Method method) {
       Assert.notNull(method, "method cannot be null");
       var tool = method.getAnnotation(Tool.class);
       if (tool == null) {
          return new DefaultToolCallResultConverter();
       }
       var type = tool.resultConverter();
       try {
          return type.getDeclaredConstructor().newInstance();
       }
       catch (Exception e) {
          throw new IllegalArgumentException("Failed to instantiate ToolCallResultConverter: " + type, e);
       }
    }

    public static List<String> getDuplicateToolNames(List<FunctionCallback> toolCallbacks) {
       Assert.notNull(toolCallbacks, "toolCallbacks cannot be null");
       return toolCallbacks.stream()
          .collect(Collectors.groupingBy(FunctionCallback::getName, Collectors.counting()))
          .entrySet()
          .stream()
          .filter(entry -> entry.getValue() > 1)
          .map(Map.Entry::getKey)
          .collect(Collectors.toList());
    }

    public static List<String> getDuplicateToolNames(FunctionCallback... toolCallbacks) {
       Assert.notNull(toolCallbacks, "toolCallbacks cannot be null");
       return getDuplicateToolNames(Arrays.asList(toolCallbacks));
    }

}

server:
  port: 8083

spring:
  application:
    name: Tool-Calling

  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}

    toolcalling:
      baidutranslate:
        enabled: true
        app-id : ${BAIDU_TRANSLATE_APP_ID}
        secret-key: ${BAIDU_TRANSLATE_SECRET_KEY}

      time:
        enabled: true

      weather:
        enabled: true
        api-key: ${WEATHER_API_KEY}

import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Description;

@Configuration
@ConditionalOnClass({GetCurrentTimeByTimeZoneIdService.class})
@ConditionalOnProperty(prefix = "spring.ai.toolcalling.time", name = "enabled", havingValue = "true")
public class TimeAutoConfiguration {

    @Bean(name = "getCityTimeFunction")
    @ConditionalOnMissingBean
    @Description("Get the time of a specified city.")
    public GetCurrentTimeByTimeZoneIdService getCityTimeFunction() {
        return new GetCurrentTimeByTimeZoneIdService();
    }

}

import com.fasterxml.jackson.annotation.JsonClassDescription;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.function.Function;

public class GetCurrentTimeByTimeZoneIdService implements Function<GetCurrentTimeByTimeZoneIdService.Request, GetCurrentTimeByTimeZoneIdService.Response> {

    private static final Logger logger = LoggerFactory.getLogger(GetCurrentTimeByTimeZoneIdService.class);

    @Override
    public GetCurrentTimeByTimeZoneIdService.Response apply(GetCurrentTimeByTimeZoneIdService.Request request) {
        String timeZoneId = request.timeZoneId;
        logger.info("The current time zone is {}", timeZoneId);
        return new Response(String.format("The current time zone is %s and the current time is " + "%s", timeZoneId,
                ZoneUtils.getTimeByZoneId(timeZoneId)));
    }

    @JsonInclude(JsonInclude.Include.NON_NULL)
    @JsonClassDescription("Get the current time based on time zone id")
    public record Request(@JsonProperty(required = true, value = "timeZoneId") @JsonPropertyDescription("Time "
            + "zone id, such as Asia/Shanghai") String timeZoneId) {
    }

    @JsonClassDescription("Current time in that time zone")
    public record Response(@JsonPropertyDescription("A description containing the current time zone and the current time in that time zone") String description) {
    }

}

import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;

public class ZoneUtils {

    public static String getTimeByZoneId(String zoneId) {

        // Get the time zone using ZoneId
        ZoneId zid = ZoneId.of(zoneId);

        // Get the current time in this time zone
        ZonedDateTime zonedDateTime = ZonedDateTime.now(zid);

        // Defining a formatter
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss z");

        // Format ZonedDateTime as a string
        String formattedDateTime = zonedDateTime.format(formatter);

        return formattedDateTime;
    }

}

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;

public class TimeTools {
    private static final Logger logger = LoggerFactory.getLogger(TimeTools.class);

    @Tool(description = "Get the time of a specified city.")
    public String  getCityTimeMethod(@ToolParam(description = "Time zone id, such as Asia/Shanghai") String timeZoneId) {
        logger.info("The current time zone is {}", timeZoneId);
        return String.format("The current time zone is %s and the current time is " + "%s", timeZoneId,
                ZoneUtils.getTimeByZoneId(timeZoneId));
    }
}

import com.yingzi.toolCalling.component.time.TimeTools;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/time")
public class TimeController {

    private final ChatClient dashScopeChatClient;

    public TimeController(ChatClient.Builder chatClientBuilder) {
        this.dashScopeChatClient = chatClientBuilder.build();
    }

    /**
     * 无工具版
     */
    @GetMapping("/chat")
    public String simpleChat(@RequestParam(value = "query", defaultValue = "请告诉我现在北京时间几点了") String query) {
        return dashScopeChatClient.prompt(query).call().content();
    }

    /**
     * 调用工具版 - function
     */
    @GetMapping("/chat-tool-function")
    public String chatTranslateFunction(@RequestParam(value = "query", defaultValue = "请告诉我现在北京时间几点了") String query) {
        return dashScopeChatClient.prompt(query).tools("getCityTimeFunction").call().content();
    }

    /**
     * 调用工具版 - method
     */
    @GetMapping("/chat-tool-method")
    public String chatTranslateMethod(@RequestParam(value = "query", defaultValue = "请告诉我现在北京时间几点了") String query) {
        return dashScopeChatClient.prompt(query).tools(new TimeTools()).call().content();
    }

}

import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Description;

@Configuration
@ConditionalOnClass(WeatherService.class)
@EnableConfigurationProperties(WeatherProperties.class)
@ConditionalOnProperty(prefix = "spring.ai.toolcalling.weather", name = "enabled", havingValue = "true")
public class WeatherAutoConfiguration {

    @Bean(name = "getWeatherFunction")
    @ConditionalOnMissingBean
    @Description("Use api.weather to get weather information.")
    public WeatherService getWeatherServiceFunction(WeatherProperties properties) {
        return new WeatherService(properties);
    }

}

@ConfigurationProperties(prefix = "spring.ai.toolcalling.weather")
public class WeatherProperties {

    private String apiKey;

    public String getApiKey() {
        return apiKey;
    }

    public void setApiKey(String apiKey) {
        this.apiKey = apiKey;
    }

}

import cn.hutool.extra.pinyin.PinyinUtil;
import com.fasterxml.jackson.annotation.JsonClassDescription;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpHeaders;
import org.springframework.util.StringUtils;
import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.web.util.UriComponentsBuilder;
import reactor.core.publisher.Mono;

import java.util.List;
import java.util.Map;
import java.util.function.Function;

public class WeatherService implements Function<WeatherService.Request, WeatherService.Response> {

    private static final Logger logger = LoggerFactory.getLogger(WeatherService.class);

    private static final String WEATHER_API_URL = "https://api.weatherapi.com/v1/forecast.json";

    private final WebClient webClient;

    private final ObjectMapper objectMapper = new ObjectMapper();

    public WeatherService(WeatherProperties properties) {
        this.webClient = WebClient.builder()
                .defaultHeader(HttpHeaders.CONTENT_TYPE, "application/x-www-form-urlencoded")
                .defaultHeader("key", properties.getApiKey())
                .build();
    }

    public static Response fromJson(Map<String, Object> json) {
        Map<String, Object> location = (Map<String, Object>) json.get("location");
        Map<String, Object> current = (Map<String, Object>) json.get("current");
        Map<String, Object> forecast = (Map<String, Object>) json.get("forecast");
        List<Map<String, Object>> forecastDays = (List<Map<String, Object>>) forecast.get("forecastday");
        String city = (String) location.get("name");
        return new Response(city, current, forecastDays);
    }

    @Override
    public Response apply(Request request) {
        if (request == null || !StringUtils.hasText(request.city())) {
            logger.error("Invalid request: city is required.");
            return null;
        }
        String location = preprocessLocation(request.city());
        String url = UriComponentsBuilder.fromHttpUrl(WEATHER_API_URL)
                .queryParam("q", location)
                .queryParam("days", request.days())
                .toUriString();
        try {
            Mono<String> responseMono = webClient.get().uri(url).retrieve().bodyToMono(String.class);
            String jsonResponse = responseMono.block();
            assert jsonResponse != null;

            Response response = fromJson(objectMapper.readValue(jsonResponse, new TypeReference<Map<String, Object>>() {
            }));
            logger.info("Weather data fetched successfully for city: {}", response.city());
            return response;
        }
        catch (Exception e) {
            logger.error("Failed to fetch weather data: {}", e.getMessage());
            return null;
        }
    }

    // Use the tools in hutool to convert Chinese place names into pinyin
    private String preprocessLocation(String location) {
        if (containsChinese(location)) {
            return PinyinUtil.getPinyin(location, "");
        }
        return location;
    }

    private boolean containsChinese(String str) {
        return str.matches(".*[\u4e00-\u9fa5].*");
    }

    @JsonInclude(JsonInclude.Include.NON_NULL)
    @JsonClassDescription("Weather Service API request")
    public record Request(
            @JsonProperty(required = true, value = "city") @JsonPropertyDescription("city name") String city,

            @JsonProperty(required = true,
                    value = "days") @JsonPropertyDescription("Number of days of weather forecast. Value ranges from 1 to 14") int days) {
    }

    @JsonClassDescription("Weather Service API response")
    public record Response(
            @JsonProperty(required = true, value = "city") @JsonPropertyDescription("city name") String city,
            @JsonProperty(required = true, value = "current") @JsonPropertyDescription("Current weather info") Map<String, Object> current,
            @JsonProperty(required = true, value = "forecastDays") @JsonPropertyDescription("Forecast weather info")
            List<Map<String, Object>> forecastDays) {
    }

}