Add conversationHistoryEnabled option to ToolCallAdvisor

Introduce a configurable option to control how conversation history is
managed during tool calling iterations in ToolCallAdvisor.

Resolves compatibility issues when using ToolCallAdvisor together with
ChatMemory advisors that manage their own conversation history.

When conversationHistoryEnabled=true (default), the advisor maintains full
conversation history internally during tool call iterations. When set to
false, only the last tool response message is passed to the next iteration,
which is useful when integrating with a Chat Memory advisor that already
manages conversation history.

- Add conversationHistoryEnabled field and builder method to ToolCallAdvisor
- Add doGetNextInstructionsForToolCall() protected method for extensibility
- Add unit tests for the new configuration option
- Update documentation in advisors-recursive.adoc and tools.adoc

Signed-off-by: Christian Tzolov <[email protected]>

Author: tzolov

spring-ai-client-chat/src/main/java/org/springframework/ai/chat/client/advisor/ToolCallAdvisor.java

@@ -16,6 +16,8 @@
 
 package org.springframework.ai.chat.client.advisor;
 
+import java.util.List;
+
 import reactor.core.publisher.Flux;
 
 import org.springframework.ai.chat.client.ChatClientRequest;
@@ -25,6 +27,7 @@
 import org.springframework.ai.chat.client.advisor.api.CallAdvisorChain;
 import org.springframework.ai.chat.client.advisor.api.StreamAdvisor;
 import org.springframework.ai.chat.client.advisor.api.StreamAdvisorChain;
+import org.springframework.ai.chat.messages.Message;
 import org.springframework.ai.chat.model.ChatResponse;
 import org.springframework.ai.chat.prompt.Prompt;
 import org.springframework.ai.model.tool.ToolCallingChatOptions;
@@ -57,13 +60,21 @@ public class ToolCallAdvisor implements CallAdvisor, StreamAdvisor {
 	 */
 	private final int advisorOrder;
 
+	private final boolean conversationHistoryEnabled;
+
 	protected ToolCallAdvisor(ToolCallingManager toolCallingManager, int advisorOrder) {
+		this(toolCallingManager, advisorOrder, true);
+	}
+
+	protected ToolCallAdvisor(ToolCallingManager toolCallingManager, int advisorOrder,
+			boolean conversationHistoryEnabled) {
 		Assert.notNull(toolCallingManager, "toolCallingManager must not be null");
 		Assert.isTrue(advisorOrder > BaseAdvisor.HIGHEST_PRECEDENCE && advisorOrder < BaseAdvisor.LOWEST_PRECEDENCE,
 				"advisorOrder must be between HIGHEST_PRECEDENCE and LOWEST_PRECEDENCE");
 
 		this.toolCallingManager = toolCallingManager;
 		this.advisorOrder = advisorOrder;
+		this.conversationHistoryEnabled = conversationHistoryEnabled;
 	}
 
 	@Override
@@ -144,7 +155,8 @@ public ChatClientResponse adviseCall(ChatClientRequest chatClientRequest, CallAd
 					break;
 				}
 
-				instructions = toolExecutionResult.conversationHistory();
+				instructions = this.doGetNextInstructionsForToolCall(processedChatClientRequest, chatClientResponse,
+						toolExecutionResult);
 			}
 
 		}
@@ -153,6 +165,17 @@ public ChatClientResponse adviseCall(ChatClientRequest chatClientRequest, CallAd
 		return this.doFinalizeLoop(chatClientResponse, callAdvisorChain);
 	}
 
+	protected List<Message> doGetNextInstructionsForToolCall(ChatClientRequest chatClientRequest,
+			ChatClientResponse chatClientResponse, ToolExecutionResult toolExecutionResult) {
+
+		if (!this.conversationHistoryEnabled) {
+			return List.of(toolExecutionResult.conversationHistory()
+				.get(toolExecutionResult.conversationHistory().size() - 1));
+		}
+
+		return toolExecutionResult.conversationHistory();
+	}
+
 	protected ChatClientResponse doFinalizeLoop(ChatClientResponse chatClientResponse,
 			CallAdvisorChain callAdvisorChain) {
 		return chatClientResponse;
@@ -199,6 +222,8 @@ public static class Builder<T extends Builder<T>> {
 
 		private int advisorOrder = BaseAdvisor.HIGHEST_PRECEDENCE + 300;
 
+		private boolean conversationHistoryEnabled = true;
+
 		protected Builder() {
 		}
 
@@ -233,6 +258,17 @@ public T advisorOrder(int advisorOrder) {
 			return self();
 		}
 
+		/**
+		 * Sets whether internal conversation history is enabled. If false, you need a
+		 * ChatMemory Advisor registered next in the chain.
+		 * @param conversationHistoryEnabled true to enable, false to disable
+		 * @return this Builder instance for method chaining
+		 */
+		public T conversationHistoryEnabled(boolean conversationHistoryEnabled) {
+			this.conversationHistoryEnabled = conversationHistoryEnabled;
+			return self();
+		}
+
 		/**
 		 * Returns the configured ToolCallingManager.
 		 * @return the ToolCallingManager instance
@@ -257,7 +293,7 @@ protected int getAdvisorOrder() {
 		 * is out of valid range
 		 */
 		public ToolCallAdvisor build() {
-			return new ToolCallAdvisor(this.toolCallingManager, this.advisorOrder);
+			return new ToolCallAdvisor(this.toolCallingManager, this.advisorOrder, this.conversationHistoryEnabled);
 		}
 
 	}

spring-ai-client-chat/src/test/java/org/springframework/ai/chat/client/advisor/ToolCallAdvisorTests.java

@@ -390,6 +390,79 @@ void testBuilderGetters() {
 		assertThat(builder.getAdvisorOrder()).isEqualTo(customOrder);
 	}
 
+	@Test
+	void testConversationHistoryEnabledDefaultValue() {
+		ToolCallAdvisor advisor = ToolCallAdvisor.builder().toolCallingManager(this.toolCallingManager).build();
+
+		// By default, conversationHistoryEnabled should be true
+		// Verify via the tool call iteration behavior - with history enabled, the full
+		// conversation history is used
+		ChatClientRequest request = createMockRequest(true);
+		ChatClientResponse responseWithToolCall = createMockResponse(true);
+		ChatClientResponse finalResponse = createMockResponse(false);
+
+		int[] callCount = { 0 };
+		CallAdvisor terminalAdvisor = new TerminalCallAdvisor((req, chain) -> {
+			callCount[0]++;
+			return callCount[0] == 1 ? responseWithToolCall : finalResponse;
+		});
+
+		CallAdvisorChain realChain = DefaultAroundAdvisorChain.builder(ObservationRegistry.NOOP)
+			.pushAll(List.of(advisor, terminalAdvisor))
+			.build();
+
+		// Mock tool execution result with multiple messages in history
+		List<Message> conversationHistory = List.of(new UserMessage("test"),
+				AssistantMessage.builder().content("").build(), ToolResponseMessage.builder().build());
+		ToolExecutionResult toolExecutionResult = ToolExecutionResult.builder()
+			.conversationHistory(conversationHistory)
+			.build();
+		when(this.toolCallingManager.executeToolCalls(any(Prompt.class), any(ChatResponse.class)))
+			.thenReturn(toolExecutionResult);
+
+		ChatClientResponse result = advisor.adviseCall(request, realChain);
+
+		assertThat(result).isEqualTo(finalResponse);
+	}
+
+	@Test
+	void testConversationHistoryEnabledSetToFalse() {
+		ToolCallAdvisor advisor = ToolCallAdvisor.builder()
+			.toolCallingManager(this.toolCallingManager)
+			.conversationHistoryEnabled(false)
+			.build();
+
+		ChatClientRequest request = createMockRequest(true);
+		ChatClientResponse responseWithToolCall = createMockResponse(true);
+		ChatClientResponse finalResponse = createMockResponse(false);
+
+		int[] callCount = { 0 };
+		CallAdvisor terminalAdvisor = new TerminalCallAdvisor((req, chain) -> {
+			callCount[0]++;
+			return callCount[0] == 1 ? responseWithToolCall : finalResponse;
+		});
+
+		CallAdvisorChain realChain = DefaultAroundAdvisorChain.builder(ObservationRegistry.NOOP)
+			.pushAll(List.of(advisor, terminalAdvisor))
+			.build();
+
+		// Mock tool execution result with multiple messages in history
+		List<Message> conversationHistory = List.of(new UserMessage("test"),
+				AssistantMessage.builder().content("").build(), ToolResponseMessage.builder().build());
+		ToolExecutionResult toolExecutionResult = ToolExecutionResult.builder()
+			.conversationHistory(conversationHistory)
+			.build();
+		when(this.toolCallingManager.executeToolCalls(any(Prompt.class), any(ChatResponse.class)))
+			.thenReturn(toolExecutionResult);
+
+		ChatClientResponse result = advisor.adviseCall(request, realChain);
+
+		assertThat(result).isEqualTo(finalResponse);
+		// With conversationHistoryEnabled=false, only the last message from history is
+		// used
+		verify(this.toolCallingManager, times(1)).executeToolCalls(any(Prompt.class), any(ChatResponse.class));
+	}
+
 	@Test
 	void testExtendedAdvisorWithCustomHooks() {
 		int[] hookCallCounts = { 0, 0, 0 }; // initializeLoop, beforeCall, afterCall
@@ -476,12 +549,13 @@ private ChatClientRequest createMockRequest(boolean withToolCallingOptions) {
 		List<Message> instructions = List.of(new UserMessage("test message"));
 
 		ChatOptions options = null;
+		ToolCallingChatOptions copiedOptions = null;
+
 		if (withToolCallingOptions) {
 			ToolCallingChatOptions toolOptions = mock(ToolCallingChatOptions.class,
 					Mockito.withSettings().strictness(Strictness.LENIENT));
 			// Create a separate mock for the copy that tracks the internal state
-			ToolCallingChatOptions copiedOptions = mock(ToolCallingChatOptions.class,
-					Mockito.withSettings().strictness(Strictness.LENIENT));
+			copiedOptions = mock(ToolCallingChatOptions.class, Mockito.withSettings().strictness(Strictness.LENIENT));
 
 			// Use a holder to track the state
 			boolean[] internalToolExecutionEnabled = { true };
@@ -501,12 +575,30 @@ private ChatClientRequest createMockRequest(boolean withToolCallingOptions) {
 				return null;
 			}).when(copiedOptions).setInternalToolExecutionEnabled(org.mockito.ArgumentMatchers.anyBoolean());
 
+			// copiedOptions.copy() should also return itself for subsequent copies
+			when(copiedOptions.copy()).thenReturn(copiedOptions);
+
 			options = toolOptions;
 		}
 
 		Prompt prompt = new Prompt(instructions, options);
+		ChatClientRequest originalRequest = ChatClientRequest.builder().prompt(prompt).build();
+
+		// Create a mock request that returns a proper copy with the mocked options chain
+		ChatClientRequest mockRequest = mock(ChatClientRequest.class,
+				Mockito.withSettings().strictness(Strictness.LENIENT));
+		when(mockRequest.prompt()).thenReturn(prompt);
+		when(mockRequest.context()).thenReturn(Map.of());
+
+		// When copy() is called, return a new request with the copied options properly
+		// set up
+		final ToolCallingChatOptions finalCopiedOptions = copiedOptions;
+		when(mockRequest.copy()).thenAnswer(invocation -> {
+			Prompt copiedPrompt = new Prompt(instructions, finalCopiedOptions);
+			return ChatClientRequest.builder().prompt(copiedPrompt).build();
+		});
 
-		return ChatClientRequest.builder().prompt(prompt).build();
+		return mockRequest;
 	}
 
 	private ChatClientResponse createMockResponse(boolean hasToolCalls) {
@@ -575,7 +667,7 @@ private static class TestableToolCallAdvisor extends ToolCallAdvisor {
 		private final int[] hookCallCounts;
 
 		TestableToolCallAdvisor(ToolCallingManager toolCallingManager, int advisorOrder, int[] hookCallCounts) {
-			super(toolCallingManager, advisorOrder);
+			super(toolCallingManager, advisorOrder, true);
 			this.hookCallCounts = hookCallCounts;
 		}
 

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/advisors-recursive.adoc

@@ -38,6 +38,7 @@ Key features:
 * Supports "return direct" functionality - when a tool execution has `returnDirect=true`, it interrupts the tool calling loop and returns the tool execution result directly to the client application instead of sending it back to the LLM
 * Uses `callAdvisorChain.copy(this)` to create a sub-chain for recursive calls
 * Includes null safety checks to handle cases where the chat response might be null
+* Supports configurable conversation history management via `conversationHistoryEnabled`
 
 Example usage:
 
@@ -53,6 +54,37 @@ var chatClient = ChatClient.builder(chatModel)
     .build();
 ----
 
+==== Conversation History Management
+
+The `ToolCallAdvisor` includes a `conversationHistoryEnabled` configuration option that controls how conversation history is managed during tool calling iterations.
+
+By default (`conversationHistoryEnabled=true`), the advisor maintains the full conversation history internally during tool call iterations. This means each subsequent LLM call in the tool calling loop includes all previous messages (user message, assistant responses, tool responses).
+
+When set to `false`, only the last tool response message is passed to the next iteration. This is useful when:
+
+* You have a Chat Memory Advisor registered next in the chain that already manages conversation history
+* You want to reduce token usage by not duplicating history management
+* You're integrating with external conversation memory systems
+
+Example with conversation history disabled:
+
+[source,java]
+----
+var toolCallAdvisor = ToolCallAdvisor.builder()
+    .toolCallingManager(toolCallingManager)
+    .conversationHistoryEnabled(false)  // Disable internal history - let ChatMemory handle it
+    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 300)
+    .build();
+
+var chatMemoryAdvisor = MessageChatMemoryAdvisor.builder(chatMemory)
+    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 200)  // Positioned before ToolCallAdvisor
+    .build();
+
+var chatClient = ChatClient.builder(chatModel)
+    .defaultAdvisors(chatMemoryAdvisor, toolCallAdvisor)
+    .build();
+----
+
 ==== Return Direct Functionality
 
 The "return direct" feature allows tools to bypass the LLM and return their results directly to the client application. This is useful when:

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/tools.adoc

@@ -1107,6 +1107,70 @@ public class DefaultToolExecutionEligibilityPredicate implements ToolExecutionEl
 
 You can provide your custom implementation of `ToolExecutionEligibilityPredicate` when creating the `ChatModel` bean.
 
+=== Advisor-Controlled Tool Execution with ToolCallAdvisor
+
+As an alternative to the framework-controlled tool execution, you can use the `ToolCallAdvisor` to implement tool calling as part of the xref:api/chatclient.adoc#_advisors[advisor chain]. This approach provides several advantages:
+
+* **Observability**: Other advisors in the chain can intercept and observe each tool call iteration
+* **Integration with Chat Memory**: Works seamlessly with Chat Memory advisors for conversation history management
+* **Extensibility**: The advisor can be extended to customize the tool calling behavior
+
+The `ToolCallAdvisor` implements the tool calling loop and disables the model's internal tool execution. When the model requests a tool call, the advisor executes the tool and sends the result back to the model, continuing until no more tool calls are needed.
+
+[source,java]
+----
+var toolCallAdvisor = ToolCallAdvisor.builder()
+    .toolCallingManager(toolCallingManager)
+    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 300)
+    .build();
+
+var chatClient = ChatClient.builder(chatModel)
+    .defaultAdvisors(toolCallAdvisor)
+    .build();
+
+String response = chatClient.prompt("What day is tomorrow?")
+    .tools(new DateTimeTools())
+    .call()
+    .content();
+----
+
+==== Configuration Options
+
+The `ToolCallAdvisor.Builder` supports the following configuration options:
+
+- `toolCallingManager`: The `ToolCallingManager` instance to use for executing tool calls. If not provided, a default instance is used.
+- `advisorOrder`: The order in which the advisor is applied in the chain. Must be between `BaseAdvisor.HIGHEST_PRECEDENCE` and `BaseAdvisor.LOWEST_PRECEDENCE`.
+- `conversationHistoryEnabled`: Controls whether the advisor maintains conversation history internally during tool call iterations. Default is `true`.
+
+==== Conversation History Management
+
+By default (`conversationHistoryEnabled=true`), the `ToolCallAdvisor` maintains the full conversation history internally during tool call iterations. Each subsequent LLM call includes all previous messages.
+
+When set to `false`, only the last tool response message is passed to the next iteration. This is useful when integrating with a Chat Memory advisor that already manages conversation history:
+
+[source,java]
+----
+var toolCallAdvisor = ToolCallAdvisor.builder()
+    .toolCallingManager(toolCallingManager)
+    .conversationHistoryEnabled(false)  // Let ChatMemory handle history
+    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 300)
+    .build();
+
+var chatMemoryAdvisor = MessageChatMemoryAdvisor.builder(chatMemory)
+    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 200)  // Before ToolCallAdvisor
+    .build();
+
+var chatClient = ChatClient.builder(chatModel)
+    .defaultAdvisors(chatMemoryAdvisor, toolCallAdvisor)
+    .build();
+----
+
+==== Return Direct
+
+The `ToolCallAdvisor` supports the "return direct" feature, allowing tools to bypass the LLM and return results directly to the client. When a tool execution has `returnDirect=true`, the advisor breaks out of the tool calling loop and returns the tool result directly.
+
+For more details about `ToolCallAdvisor`, see xref:api/advisors-recursive.adoc#_toolcalladvisor[Recursive Advisors - ToolCallAdvisor].
+
 === User-Controlled Tool Execution
 
 There are cases where you'd rather control the tool execution lifecycle yourself. You can do so by setting the `internalToolExecutionEnabled` attribute of `ToolCallingChatOptions` to `false`.