|
| 1 | +# Migrating from FunctionCallback to ToolCallback API |
| 2 | + |
| 3 | +This guide helps you migrate from the deprecated FunctionCallback API to the new ToolCallback API in Spring AI. |
| 4 | + |
| 5 | +## Overview of Changes |
| 6 | + |
| 7 | +The Spring AI project is moving from "functions" to "tools" terminology to better align with industry standards. This involves several API changes while maintaining backward compatibility through deprecated methods. |
| 8 | + |
| 9 | +## Key Changes |
| 10 | + |
| 11 | +1. `FunctionCallback` → `ToolCallback` |
| 12 | +2. `FunctionCallback.builder().functions()` → `FunctionToolCallback.builder()` |
| 13 | +3. `FunctionCallback.builder().method()` → `MethodToolCallback.builder()` |
| 14 | +4. `FunctionCallingOptions` → `ToolCallingChatOptions` |
| 15 | +5. Method names from `functions()` → `tools()` |
| 16 | + |
| 17 | +## Migration Examples |
| 18 | + |
| 19 | +### 1. Basic Function Callback |
| 20 | + |
| 21 | +Before: |
| 22 | +```java |
| 23 | +FunctionCallback.builder() |
| 24 | + .function("getCurrentWeather", new MockWeatherService()) |
| 25 | + .description("Get the weather in location") |
| 26 | + .inputType(MockWeatherService.Request.class) |
| 27 | + .build() |
| 28 | +``` |
| 29 | + |
| 30 | +After: |
| 31 | +```java |
| 32 | +FunctionToolCallback.builder("getCurrentWeather", new MockWeatherService()) |
| 33 | + .description("Get the weather in location") |
| 34 | + .inputType(MockWeatherService.Request.class) |
| 35 | + .build() |
| 36 | +``` |
| 37 | + |
| 38 | +### 2. ChatClient Usage |
| 39 | + |
| 40 | +Before: |
| 41 | +```java |
| 42 | +String response = ChatClient.create(chatModel) |
| 43 | + .prompt() |
| 44 | + .user("What's the weather like in San Francisco?") |
| 45 | + .functions(FunctionCallback.builder() |
| 46 | + .function("getCurrentWeather", new MockWeatherService()) |
| 47 | + .description("Get the weather in location") |
| 48 | + .inputType(MockWeatherService.Request.class) |
| 49 | + .build()) |
| 50 | + .call() |
| 51 | + .content(); |
| 52 | +``` |
| 53 | + |
| 54 | +After: |
| 55 | +```java |
| 56 | +String response = ChatClient.create(chatModel) |
| 57 | + .prompt() |
| 58 | + .user("What's the weather like in San Francisco?") |
| 59 | + .tools(FunctionToolCallback.builder("getCurrentWeather", new MockWeatherService()) |
| 60 | + .description("Get the weather in location") |
| 61 | + .inputType(MockWeatherService.Request.class) |
| 62 | + .build()) |
| 63 | + .call() |
| 64 | + .content(); |
| 65 | +``` |
| 66 | + |
| 67 | +### 3. Method-Based Function Callbacks |
| 68 | + |
| 69 | +Before: |
| 70 | +```java |
| 71 | +FunctionCallback.builder() |
| 72 | + .method("getWeatherInLocation", String.class, Unit.class) |
| 73 | + .description("Get the weather in location") |
| 74 | + .targetClass(TestFunctionClass.class) |
| 75 | + .build() |
| 76 | +``` |
| 77 | + |
| 78 | +After: |
| 79 | +```java |
| 80 | +var toolMethod = ReflectionUtils.findMethod( |
| 81 | + TestFunctionClass.class, "getWeatherInLocation", String.class, Unit.class); |
| 82 | + |
| 83 | +MethodToolCallback.builder() |
| 84 | + .toolDefinition(ToolDefinition.builder(toolMethod) |
| 85 | + .description("Get the weather in location") |
| 86 | + .build()) |
| 87 | + .toolMethod(toolMethod) |
| 88 | + .build() |
| 89 | +``` |
| 90 | + |
| 91 | +And you can use the same `ChatClient#tools()` API to register method-based tool callbackes: |
| 92 | + |
| 93 | +```java |
| 94 | +String response = ChatClient.create(chatModel) |
| 95 | + .prompt() |
| 96 | + .user("What's the weather like in San Francisco?") |
| 97 | + .tools(MethodToolCallback.builder() |
| 98 | + .toolDefinition(ToolDefinition.builder(toolMethod) |
| 99 | + .description("Get the weather in location") |
| 100 | + .build()) |
| 101 | + .toolMethod(toolMethod) |
| 102 | + .build()) |
| 103 | + .call() |
| 104 | + .content(); |
| 105 | +``` |
| 106 | + |
| 107 | +### 4. Options Configuration |
| 108 | + |
| 109 | +Before: |
| 110 | +```java |
| 111 | +FunctionCallingOptions.builder() |
| 112 | + .model(modelName) |
| 113 | + .function("weatherFunction") |
| 114 | + .build() |
| 115 | +``` |
| 116 | + |
| 117 | +After: |
| 118 | +```java |
| 119 | +ToolCallingChatOptions.builder() |
| 120 | + .model(modelName) |
| 121 | + .tools("weatherFunction") |
| 122 | + .build() |
| 123 | +``` |
| 124 | + |
| 125 | +### 5. Default Functions in ChatClient Builder |
| 126 | + |
| 127 | +Before: |
| 128 | +```java |
| 129 | +ChatClient.builder(chatModel) |
| 130 | + .defaultFunctions(FunctionCallback.builder() |
| 131 | + .function("getCurrentWeather", new MockWeatherService()) |
| 132 | + .description("Get the weather in location") |
| 133 | + .inputType(MockWeatherService.Request.class) |
| 134 | + .build()) |
| 135 | + .build() |
| 136 | +``` |
| 137 | + |
| 138 | +After: |
| 139 | +```java |
| 140 | +ChatClient.builder(chatModel) |
| 141 | + .defaultTools(FunctionToolCallback.builder("getCurrentWeather", new MockWeatherService()) |
| 142 | + .description("Get the weather in location") |
| 143 | + .inputType(MockWeatherService.Request.class) |
| 144 | + .build()) |
| 145 | + .build() |
| 146 | +``` |
| 147 | + |
| 148 | +### 6. Spring Bean Configuration |
| 149 | + |
| 150 | +Before: |
| 151 | +```java |
| 152 | +@Bean |
| 153 | +public FunctionCallback weatherFunctionInfo() { |
| 154 | + return FunctionCallback.builder() |
| 155 | + .function("WeatherInfo", new MockWeatherService()) |
| 156 | + .description("Get the current weather") |
| 157 | + .inputType(MockWeatherService.Request.class) |
| 158 | + .build(); |
| 159 | +} |
| 160 | +``` |
| 161 | + |
| 162 | +After: |
| 163 | +```java |
| 164 | +@Bean |
| 165 | +public ToolCallback weatherFunctionInfo() { |
| 166 | + return FunctionToolCallback.builder("WeatherInfo", new MockWeatherService()) |
| 167 | + .description("Get the current weather") |
| 168 | + .inputType(MockWeatherService.Request.class) |
| 169 | + .build(); |
| 170 | +} |
| 171 | +``` |
| 172 | + |
| 173 | +## Breaking Changes |
| 174 | + |
| 175 | +1. The `method()` configuration in function callbacks has been replaced with a more explicit method tool configuration using `ToolDefinition` and `MethodToolCallback`. |
| 176 | + |
| 177 | +2. When using method-based callbacks, you now need to explicitly find the method using `ReflectionUtils` and provide it to the builder. |
| 178 | + |
| 179 | +3. For non-static methods, you must now provide both the method and the target object: |
| 180 | +```java |
| 181 | +MethodToolCallback.builder() |
| 182 | + .toolDefinition(ToolDefinition.builder(toolMethod) |
| 183 | + .description("Description") |
| 184 | + .build()) |
| 185 | + .toolMethod(toolMethod) |
| 186 | + .toolObject(targetObject) |
| 187 | + .build() |
| 188 | +``` |
| 189 | + |
| 190 | +## Deprecated Methods |
| 191 | + |
| 192 | +The following methods are deprecated and will be removed in a future release: |
| 193 | + |
| 194 | +- `ChatClient.Builder.defaultFunctions(String...)` |
| 195 | +- `ChatClient.Builder.defaultFunctions(FunctionCallback...)` |
| 196 | +- `ChatClient.RequestSpec.functions()` |
| 197 | + |
| 198 | +Use their `tools` counterparts instead. |
| 199 | + |
| 200 | +## @Tool tool definition path. |
| 201 | + |
| 202 | +Now you can use the method-level annothation (`@Tool`) to register tools with Spring AI |
| 203 | + |
| 204 | +```java |
| 205 | +public class Home { |
| 206 | + |
| 207 | + @Tool(description = "Turn light On or Off in a room.") |
| 208 | + public void turnLight(String roomName, boolean on) { |
| 209 | + // ... |
| 210 | + logger.info("Turn light in room: {} to: {}", roomName, on); |
| 211 | + } |
| 212 | +} |
| 213 | + |
| 214 | +Home homeAutomation = new HomeAutomation(); |
| 215 | + |
| 216 | +String response = ChatClient.create(this.chatModel).prompt() |
| 217 | + .user("Turn the light in the living room On.") |
| 218 | + .tools(homeAutomation) |
| 219 | + .call() |
| 220 | + .content(); |
| 221 | + |
| 222 | +``` |
| 223 | + |
| 224 | + |
| 225 | +## Additional Notes |
| 226 | + |
| 227 | +1. The new API provides better separation between tool definition and implementation. |
| 228 | +2. Tool definitions can be reused across different implementations. |
| 229 | +3. The builder pattern has been simplified for common use cases. |
| 230 | +4. Better support for method-based tools with improved error handling. |
| 231 | + |
| 232 | +## Timeline |
| 233 | + |
| 234 | +The deprecated methods will be maintained for backward compatibility in the current major version but will be removed in the next major release. It's recommended to migrate to the new API as soon as possible. |
0 commit comments