Add breaking changes to 1.0 M8 upgrade notes regarding chatclient tool calling
This commit is contained in:
Mark Pollack
@@ -25,24 +25,6 @@ For details, refer to:
|
||||
- xref:upgrade-notes.adoc#common-package-changes[Common Package Changes]
|
||||
- xref:upgrade-notes.adoc#common-module-structure[Common Module Structure]
|
||||
|
||||
[[automating-upgrading-using-ai]]
|
||||
=== Automating upgrading using AI
|
||||
|
||||
You can automate the upgrade process to 1.0.0-SNAPSHOT using the Claude Code CLI tool with a provided prompt. The prompt will guide the AI to perform the following tasks:
|
||||
|
||||
1. Update the Spring AI BOM version to 1.0.0-SNAPSHOT
|
||||
2. Ensure all required repositories exist in your build configuration
|
||||
3. Update Spring AI artifact IDs according to the new naming patterns
|
||||
|
||||
To use this automation:
|
||||
|
||||
1. Download the https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview[Claude Code CLI tool]
|
||||
2. Copy the prompt from the https://github.com/spring-projects/spring-ai/blob/main/src/prompts/update-to-snapshot.txt[update-to-snapshot.txt] file
|
||||
3. Paste the prompt into the Claude Code CLI
|
||||
4. The AI will analyze your project and make the necessary changes
|
||||
|
||||
This approach can save time and reduce the chance of errors when upgrading multiple projects or complex codebases.
|
||||
|
||||
[[upgrading-to-1-0-0-m8]]
|
||||
== Upgrading to 1.0.0-M8
|
||||
|
||||
@@ -50,6 +32,74 @@ You can automate the upgrade process to 1.0.0-M8 using an OpenRewrite recipe.
|
||||
This recipe helps apply many of the necessary code changes for this version.
|
||||
Find the recipe and usage instructions at https://github.com/arconia-io/arconia-migrations/blob/main/docs/spring-ai.md[Arconia Spring AI Migrations].
|
||||
|
||||
=== Breaking Changes
|
||||
When upgrading from Spring AI 1.0 M7 to 1.0 M8, users who previously registered tool callbacks are encountering breaking changes that cause tool calling functionality to silently fail. This is specifically impacting code that used the deprecated `tools()` method.
|
||||
|
||||
==== Example
|
||||
|
||||
Here's an example of code that worked in M7 but no longer functions as expected in M8:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// Old code in M7 - no longer works correctly in M8
|
||||
chatClient.prompt("What day is tomorrow?")
|
||||
.tools(toolCallback)
|
||||
.call()
|
||||
.content();
|
||||
----
|
||||
|
||||
==== How to Adapt Your Code
|
||||
|
||||
To fix this issue when upgrading to M8, you need to update your code to use the new `toolCallbacks()` method:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// Updated code for M8
|
||||
chatClient.prompt("What day is tomorrow?")
|
||||
.toolCallbacks(toolCallback)
|
||||
.call()
|
||||
.content();
|
||||
----
|
||||
|
||||
==== Why This Change Was Made
|
||||
|
||||
The Spring AI team renamed the overloaded `tools()` methods to improve clarity and prevent ambiguity in method dispatching. The previous API design led to confusion when the Java compiler needed to select between multiple overloaded methods based on parameter types.
|
||||
|
||||
==== Method Mapping from M7 to M8
|
||||
|
||||
Here's how the old methods map to their new counterparts:
|
||||
|
||||
1. `tools(String... toolNames)` → `toolNames(String... toolNames)`
|
||||
- Use when referring to tools registered elsewhere (e.g., via `@Bean` with `@Description`)
|
||||
|
||||
2. `tools(ToolCallback... toolCallbacks)` → `toolCallbacks(ToolCallback... toolCallbacks)`
|
||||
- Use for inline tool callback registration
|
||||
|
||||
3. `tools(List<ToolCallback> toolCallbacks)` → `toolCallbacks(List<ToolCallback> toolCallbacks)`
|
||||
- Use when you have a collection of tool callbacks
|
||||
|
||||
4. `tools(ToolCallbackProvider... toolCallbackProviders)` → `toolCallbacks(ToolCallbackProvider... toolCallbackProviders)`
|
||||
- Use for objects implementing the `ToolCallbackProvider` interface
|
||||
|
||||
5. `tools(Object... toolObjects)` remains unchanged
|
||||
- Use only for objects with methods annotated with `@Tool`
|
||||
|
||||
==== Improved Error Handling
|
||||
|
||||
In the https://github.com/spring-projects/spring-ai/pull/2964[this PR now merged (spring-projects/spring-ai#2964)], the `tools(Object... toolObjects)` method will now throw an exception when no `@Tool` methods are found on the provided objects, rather than silently failing. This helps developers identify migration issues immediately.
|
||||
|
||||
==== Migration Summary
|
||||
|
||||
If you're upgrading from M7 to M8:
|
||||
|
||||
1. Replace all calls to `.tools(toolCallback)` with `.toolCallbacks(toolCallback)`
|
||||
2. Replace all calls to `.tools(toolCallbackProvider)` with `.toolCallbacks(toolCallbackProvider)`
|
||||
3. Replace all calls to `.tools("toolName")` with `.toolNames("toolName")`
|
||||
|
||||
These changes will ensure your tool calling functionality continues to work correctly after upgrading to Spring AI 1.0 M8.
|
||||
|
||||
|
||||
|
||||
=== Chat Client
|
||||
|
||||
* The `ChatClient` has been enhanced to solve some inconsistencies or unwanted behavior whenever user and system prompts were not rendered before using them in an advisor. The new behavior ensures that the user and system prompts are always rendered before executing the chain of advisors. As part of this enhancement, the `AdvisedRequest` and `AdvisedResponse` APIs have been deprecated, replaced by `ChatClientRequest` and `ChatClientResponse`. Advisors now act on a fully built `Prompt` object included in a `ChatClientRequest` instead of the destructured format used in `AdvisedRequest`, guaranteeing consistency and completeness.
|
||||
|
||||
Reference in New Issue
Block a user