このバージョンはまだ開発中であり、まだ安定しているとは考えられていません。最新のスナップショットバージョンについては、Spring AI 1.0.3 を使用してください。

FunctionCallback から ToolCallback API への移行

このガイドは、非推奨となりた FunctionCallback API から Spring AI の新しい ToolCallback API への移行に役立ちます。新しい API の詳細については、ツール呼び出しのドキュメントを参照してください。

変更の概要

これらの変更は、Spring AI のツール呼び出し機能を改善および拡張するための幅広い取り組みの一環です。特に、新しい API では、業界の慣習に合わせるために「関数」という用語が「ツール」に変更されています。これには、非推奨のメソッドを通じて下位互換性を維持しながら、いくつかの API 変更が含まれます。

主な変更点

FunctionCallback → ToolCallback
FunctionCallback.builder().function() → FunctionToolCallback.builder()
FunctionCallback.builder().method() → MethodToolCallback.builder()
FunctionCallingOptions → ToolCallingChatOptions
ChatClient.builder().defaultFunctions() → ChatClient.builder().defaultTools()
ChatClient.functions() → ChatClient.tools()
FunctionCallingOptions.builder().functions() → ToolCallingChatOptions.builder().toolNames()
FunctionCallingOptions.builder().functionCallbacks() → ToolCallingChatOptions.builder().toolCallbacks()

移行例

1. 基本関数コールバック

次の前で改ページ:

FunctionCallback.builder()
    .function("getCurrentWeather", new MockWeatherService())
    .description("Get the weather in location")
    .inputType(MockWeatherService.Request.class)
    .build()

次の後で改ページ:

FunctionToolCallback.builder("getCurrentWeather", new MockWeatherService())
    .description("Get the weather in location")
    .inputType(MockWeatherService.Request.class)
    .build()

2. ChatClient の使用箇所

次の前で改ページ:

String response = ChatClient.create(chatModel)
    .prompt()
    .user("What's the weather like in San Francisco?")
    .functions(FunctionCallback.builder()
        .function("getCurrentWeather", new MockWeatherService())
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build())
    .call()
    .content();

次の後で改ページ:

String response = ChatClient.create(chatModel)
    .prompt()
    .user("What's the weather like in San Francisco?")
    .tools(FunctionToolCallback.builder("getCurrentWeather", new MockWeatherService())
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build())
    .call()
    .content();

3. メソッドベースの関数コールバック

次の前で改ページ:

FunctionCallback.builder()
    .method("getWeatherInLocation", String.class, Unit.class)
    .description("Get the weather in location")
    .targetClass(TestFunctionClass.class)
    .build()

次の後で改ページ:

var toolMethod = ReflectionUtils.findMethod(TestFunctionClass.class, "getWeatherInLocation");

MethodToolCallback.builder()
    .toolDefinition(ToolDefinition.builder(toolMethod)
        .description("Get the weather in location")
        .build())
    .toolMethod(toolMethod)
    .build()

あるいは宣言的なアプローチでは次のようになります。

class WeatherTools {

    @Tool(description = "Get the weather in location")
    public void getWeatherInLocation(String location, Unit unit) {
        // ...
    }

}

また、同じ ChatClient#tools() API を使用して、メソッドベースのツールコールバックを登録することもできます。

String response = ChatClient.create(chatModel)
    .prompt()
    .user("What's the weather like in San Francisco?")
    .tools(MethodToolCallback.builder()
        .toolDefinition(ToolDefinition.builder(toolMethod)
            .description("Get the weather in location")
            .build())
        .toolMethod(toolMethod)
        .build())
    .call()
    .content();

あるいは宣言的なアプローチでは次のようになります。

String response = ChatClient.create(chatModel)
    .prompt()
    .user("What's the weather like in San Francisco?")
    .tools(new WeatherTools())
    .call()
    .content();

4. オプション設定

次の前で改ページ:

FunctionCallingOptions.builder()
    .model(modelName)
    .function("weatherFunction")
    .build()

次の後で改ページ:

ToolCallingChatOptions.builder()
    .model(modelName)
    .toolNames("weatherFunction")
    .build()

5. ChatClient ビルダーのデフォルト機能

次の前で改ページ:

ChatClient.builder(chatModel)
    .defaultFunctions(FunctionCallback.builder()
        .function("getCurrentWeather", new MockWeatherService())
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build())
    .build()

次の後で改ページ:

ChatClient.builder(chatModel)
    .defaultTools(FunctionToolCallback.builder("getCurrentWeather", new MockWeatherService())
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build())
    .build()

6. Spring Bean の構成

次の前で改ページ:

@Bean
public FunctionCallback weatherFunctionInfo() {
    return FunctionCallback.builder()
        .function("WeatherInfo", new MockWeatherService())
        .description("Get the current weather")
        .inputType(MockWeatherService.Request.class)
        .build();
}

次の後で改ページ:

@Bean
public ToolCallback weatherFunctionInfo() {
    return FunctionToolCallback.builder("WeatherInfo", new MockWeatherService())
        .description("Get the current weather")
        .inputType(MockWeatherService.Request.class)
        .build();
}

重大な変更

関数コールバックの method() 構成は、ToolDefinition と MethodToolCallback を使用したより明示的なメソッドツール構成に置き換えられました。
メソッドベースのコールバックを使用する場合は、ReflectionUtils を使用してメソッドを明示的に検索し、ビルダーに提供する必要があります。または、@Tool アノテーションを使用した宣言的なアプローチを使用することもできます。
非静的メソッドの場合、メソッドとターゲットオブジェクトの両方を指定する必要があります。

MethodToolCallback.builder()
    .toolDefinition(ToolDefinition.builder(toolMethod)
        .description("Description")
        .build())
    .toolMethod(toolMethod)
    .toolObject(targetObject)
    .build()

非推奨のメソッド

以下のメソッドは非推奨であり、将来のリリースで削除される予定です。

ChatClient.Builder.defaultFunctions(String…)
ChatClient.Builder.defaultFunctions(FunctionCallback…)
ChatClient.RequestSpec.functions()

代わりに、対応する tools を使用してください。

@Tool による宣言的仕様

これで、メソッドレベルのアノテーション (@Tool) を使用して、Spring AI にツールを登録できるようになりました。

class Home {

    @Tool(description = "Turn light On or Off in a room.")
    void turnLight(String roomName, boolean on) {
        // ...
        logger.info("Turn light in room: {} to: {}", roomName, on);
    }
}

String response = ChatClient.create(this.chatModel).prompt()
        .user("Turn the light in the living room On.")
        .tools(new Home())
        .call()
        .content();

追加メモ

新しい API により、ツールの定義と実装がより適切に分離されます。
ツール定義は、さまざまな実装間で再利用できます。
ビルダーパターンは、一般的なユースケースに合わせて簡素化されています。
エラー処理が改善され、メソッドベースのツールのサポートが向上しました。

タイムライン

非推奨のメソッドは、現在のマイルストーンバージョンでは下位互換性のために維持されますが、次のマイルストーンリリースでは削除されます。できるだけ早く新しい API に移行することをお勧めします。