Make ChatClient and Advisor APIs more robust - Part 2

* ChatClient observations now include the full prompt content instead of just the userText and systemText. Furthermore, they include consistent telemetry for the tools passed via the ChatClient and a first-class conversation ID when using memory advisors. Incomplete or unsafe attributes have been deprecated.
* Adopted the new robust Advisor APIs for BaseAdvisor and RetrievalAugmentationAdvisor.
* Improved the prompt augmentation facilities in ChatClientRequest and Prompt for performance and immutability.
* Fixed integration test racing condition.
* Updated the documentation for ChatClient and Observability accordingly.
* Documented changes in upgrade notes.
* Introduced `prompt.augmentUserMessage(String text)` to directly replace the user message content.
* Added `prompt.augmentUserMessage(Function<UserMessage, UserMessage> augmenter)` for more granular updates using the `userMessage.mutate()` pattern, allowing modification of text, media, and metadata.

Relates to gh-2655

Signed-off-by: Thomas Vitale <[email protected]>

Author: ThomasVitale

auto-configurations/models/chat/client/spring-ai-autoconfigure-model-chat-client/src/main/java/org/springframework/ai/model/chat/client/autoconfigure/ChatClientAutoConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,6 +24,7 @@
 import org.springframework.ai.chat.client.ChatClientCustomizer;
 import org.springframework.ai.chat.client.observation.ChatClientInputContentObservationFilter;
 import org.springframework.ai.chat.client.observation.ChatClientObservationConvention;
+import org.springframework.ai.chat.client.observation.ChatClientPromptContentObservationFilter;
 import org.springframework.ai.chat.model.ChatModel;
 import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
@@ -79,14 +80,28 @@ ChatClient.Builder chatClientBuilder(ChatClientBuilderConfigurer chatClientBuild
 		return chatClientBuilderConfigurer.configure(builder);
 	}
 
+	/**
+	 * @deprecated in favour of {@link #chatClientPromptContentObservationFilter()}.
+	 */
 	@Bean
 	@ConditionalOnMissingBean
 	@ConditionalOnProperty(prefix = ChatClientBuilderProperties.CONFIG_PREFIX + ".observations", name = "include-input",
 			havingValue = "true")
+	@Deprecated
 	ChatClientInputContentObservationFilter chatClientInputContentObservationFilter() {
 		logger.warn(
 				"You have enabled the inclusion of the input content in the observations, with the risk of exposing sensitive or private information. Please, be careful!");
 		return new ChatClientInputContentObservationFilter();
 	}
 
+	@Bean
+	@ConditionalOnMissingBean
+	@ConditionalOnProperty(prefix = ChatClientBuilderProperties.CONFIG_PREFIX + ".observations",
+			name = "include-prompt", havingValue = "true")
+	ChatClientPromptContentObservationFilter chatClientPromptContentObservationFilter() {
+		logger.warn(
+				"You have enabled the inclusion of the ChatClient prompt content in the observations, with the risk of exposing sensitive or private information. Please, be careful!");
+		return new ChatClientPromptContentObservationFilter();
+	}
+
 }

auto-configurations/models/chat/client/spring-ai-autoconfigure-model-chat-client/src/main/java/org/springframework/ai/model/chat/client/autoconfigure/ChatClientBuilderProperties.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,6 +17,7 @@
 package org.springframework.ai.model.chat.client.autoconfigure;
 
 import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.boot.context.properties.DeprecatedConfigurationProperty;
 
 /**
  * Configuration properties for the chat client builder.
@@ -25,6 +26,7 @@
  * @author Mark Pollack
  * @author Josh Long
  * @author Arjen Poutsma
+ * @author Thomas Vitale
  * @since 1.0.0
  */
 @ConfigurationProperties(ChatClientBuilderProperties.CONFIG_PREFIX)
@@ -37,7 +39,7 @@ public class ChatClientBuilderProperties {
 	 */
 	private boolean enabled = true;
 
-	private Observations observations = new Observations();
+	private final Observations observations = new Observations();
 
 	public Observations getObservations() {
 		return this.observations;
@@ -55,9 +57,17 @@ public static class Observations {
 
 		/**
 		 * Whether to include the input content in the observations.
+		 * @deprecated Use {@link #includePrompt} instead.
 		 */
+		@Deprecated
 		private boolean includeInput = false;
 
+		/**
+		 * Whether to include the prompt content in the observations.
+		 */
+		private boolean includePrompt = false;
+
+		@DeprecatedConfigurationProperty(replacement = "spring.ai.chat.observations.include-prompt")
 		public boolean isIncludeInput() {
 			return this.includeInput;
 		}
@@ -66,6 +76,14 @@ public void setIncludeInput(boolean includeCompletion) {
 			this.includeInput = includeCompletion;
 		}
 
+		public boolean isIncludePrompt() {
+			return this.includePrompt;
+		}
+
+		public void setIncludePrompt(boolean includePrompt) {
+			this.includePrompt = includePrompt;
+		}
+
 	}
 
 }

auto-configurations/models/chat/client/spring-ai-autoconfigure-model-chat-client/src/test/java/org/springframework/ai/model/chat/client/autoconfigure/ChatClientObservationAutoConfigurationTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,6 +19,7 @@
 import org.junit.jupiter.api.Test;
 
 import org.springframework.ai.chat.client.observation.ChatClientInputContentObservationFilter;
+import org.springframework.ai.chat.client.observation.ChatClientPromptContentObservationFilter;
 import org.springframework.boot.autoconfigure.AutoConfigurations;
 import org.springframework.boot.test.context.runner.ApplicationContextRunner;
 
@@ -28,6 +29,7 @@
  * Unit tests for {@link ChatClientAutoConfiguration} observability support.
  *
  * @author Christian Tzolov
+ * @author Thomas Vitale
  */
 class ChatClientObservationAutoConfigurationTests {
 
@@ -46,4 +48,16 @@ void inputContentFilterEnabled() {
 			.run(context -> assertThat(context).hasSingleBean(ChatClientInputContentObservationFilter.class));
 	}
 
+	@Test
+	void promptContentFilterDefault() {
+		this.contextRunner
+			.run(context -> assertThat(context).doesNotHaveBean(ChatClientPromptContentObservationFilter.class));
+	}
+
+	@Test
+	void promptContentFilterEnabled() {
+		this.contextRunner.withPropertyValues("spring.ai.chat.client.observations.include-prompt=true")
+			.run(context -> assertThat(context).hasSingleBean(ChatClientPromptContentObservationFilter.class));
+	}
+
 }

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

@@ -21,7 +21,10 @@
  *
  * @author Thomas Vitale
  * @since 1.0.0
+ * @deprecated only introduced to smooth the transition to the new APIs and ensure
+ * backward compatibility
  */
+@Deprecated
 public enum ChatClientAttributes {
 
 	//@formatter:off

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

@@ -39,8 +39,12 @@ public record ChatClientRequest(Prompt prompt, Map<String, Object> context) {
 		Assert.noNullElements(context.keySet(), "context keys cannot be null");
 	}
 
+	public ChatClientRequest copy() {
+		return new ChatClientRequest(this.prompt.copy(), new HashMap<>(this.context));
+	}
+
 	public Builder mutate() {
-		return new Builder().prompt(this.prompt).context(this.context);
+		return new Builder().prompt(this.prompt.copy()).context(new HashMap<>(this.context));
 	}
 
 	public static Builder builder() {

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

@@ -38,6 +38,14 @@ public record ChatClientResponse(@Nullable ChatResponse chatResponse, Map<String
 		Assert.noNullElements(context.keySet(), "context keys cannot be null");
 	}
 
+	public ChatClientResponse copy() {
+		return new ChatClientResponse(this.chatResponse, new HashMap<>(this.context));
+	}
+
+	public Builder mutate() {
+		return new Builder().chatResponse(this.chatResponse).context(new HashMap<>(this.context));
+	}
+
 	public static Builder builder() {
 		return new Builder();
 	}
@@ -51,7 +59,7 @@ public static class Builder {
 		private Builder() {
 		}
 
-		public Builder chatResponse(ChatResponse chatResponse) {
+		public Builder chatResponse(@Nullable ChatResponse chatResponse) {
 			this.chatResponse = chatResponse;
 			return this;
 		}

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

@@ -493,10 +493,11 @@ private ChatClientResponse doGetObservableChatClientResponse(ChatClientRequest c
 		private ChatClientResponse doGetObservableChatClientResponse(ChatClientRequest chatClientRequest,
 				@Nullable String outputFormat) {
 			ChatClientRequest formattedChatClientRequest = StringUtils.hasText(outputFormat)
-					? addFormatInstructionsToPrompt(chatClientRequest, outputFormat) : chatClientRequest;
+					? augmentPromptWithFormatInstructions(chatClientRequest, outputFormat) : chatClientRequest;
 
 			ChatClientObservationContext observationContext = ChatClientObservationContext.builder()
 				.request(formattedChatClientRequest)
+				.advisors(advisorChain.getCallAdvisors())
 				.stream(false)
 				.withFormat(outputFormat)
 				.build();
@@ -511,42 +512,16 @@ private ChatClientResponse doGetObservableChatClientResponse(ChatClientRequest c
 		}
 
 		@NonNull
-		private static ChatClientRequest addFormatInstructionsToPrompt(ChatClientRequest chatClientRequest,
+		private static ChatClientRequest augmentPromptWithFormatInstructions(ChatClientRequest chatClientRequest,
 				String outputFormat) {
-			List<Message> originalMessages = chatClientRequest.prompt().getInstructions();
-
-			if (CollectionUtils.isEmpty(originalMessages)) {
-				return chatClientRequest;
-			}
-
-			// Create a copy of the message list to avoid modifying the original.
-			List<Message> modifiedMessages = new ArrayList<>(originalMessages);
-
-			// Get the last message (without removing it from original list)
-			Message lastMessage = modifiedMessages.get(modifiedMessages.size() - 1);
-
-			// If the last message is a UserMessage, replace it with the modified version
-			if (lastMessage instanceof UserMessage userMessage) {
-				// Remove last message
-				modifiedMessages.remove(modifiedMessages.size() - 1);
-
-				// Create new user message with format instructions
-				UserMessage userMessageWithFormat = userMessage.mutate()
+			Prompt augmentedPrompt = chatClientRequest.prompt()
+				.augmentUserMessage(userMessage -> userMessage.mutate()
 					.text(userMessage.getText() + System.lineSeparator() + outputFormat)
-					.build();
-
-				// Add modified message back
-				modifiedMessages.add(userMessageWithFormat);
-
-				// Build new ChatClientRequest preserving all properties but with modified
-				// prompt
-				return ChatClientRequest.builder()
-					.prompt(chatClientRequest.prompt().mutate().messages(modifiedMessages).build())
-					.context(Map.copyOf(chatClientRequest.context()))
-					.build();
-			}
-
-			return chatClientRequest;
+					.build());
+			return ChatClientRequest.builder()
+				.prompt(augmentedPrompt)
+				.context(Map.copyOf(chatClientRequest.context()))
+				.build();
 		}
 
 		@Nullable
@@ -588,6 +563,7 @@ private Flux<ChatClientResponse> doGetObservableFluxChatResponse(ChatClientReque
 
 				ChatClientObservationContext observationContext = ChatClientObservationContext.builder()
 					.request(chatClientRequest)
+					.advisors(advisorChain.getStreamAdvisors())
 					.stream(true)
 					.build();
 
@@ -660,8 +636,6 @@ public static class DefaultChatClientRequestSpec implements ChatClientRequestSpe
 
 		private final Map<String, Object> advisorParams = new HashMap<>();
 
-		private final DefaultAroundAdvisorChain.Builder aroundAdvisorChainBuilder;
-
 		private final Map<String, Object> toolContext = new HashMap<>();
 
 		@Nullable
@@ -718,14 +692,6 @@ public DefaultChatClientRequestSpec(ChatModel chatModel, @Nullable String userTe
 			this.observationConvention = observationConvention != null ? observationConvention
 					: DEFAULT_CHAT_CLIENT_OBSERVATION_CONVENTION;
 			this.toolContext.putAll(toolContext);
-
-			// At the stack bottom add the model call advisors.
-			// They play the role of the last advisors in the advisor chain.
-			this.advisors.add(new ChatModelCallAdvisor(chatModel));
-			this.advisors.add(new ChatModelStreamAdvisor(chatModel));
-
-			this.aroundAdvisorChainBuilder = DefaultAroundAdvisorChain.builder(observationRegistry)
-				.pushAll(this.advisors);
 		}
 
 		private ObservationRegistry getObservationRegistry() {
@@ -822,23 +788,20 @@ public ChatClientRequestSpec advisors(Consumer<ChatClient.AdvisorSpec> consumer)
 			consumer.accept(advisorSpec);
 			this.advisorParams.putAll(advisorSpec.getParams());
 			this.advisors.addAll(advisorSpec.getAdvisors());
-			this.aroundAdvisorChainBuilder.pushAll(advisorSpec.getAdvisors());
 			return this;
 		}
 
 		public ChatClientRequestSpec advisors(Advisor... advisors) {
 			Assert.notNull(advisors, "advisors cannot be null");
 			Assert.noNullElements(advisors, "advisors cannot contain null elements");
 			this.advisors.addAll(Arrays.asList(advisors));
-			this.aroundAdvisorChainBuilder.pushAll(Arrays.asList(advisors));
 			return this;
 		}
 
 		public ChatClientRequestSpec advisors(List<Advisor> advisors) {
 			Assert.notNull(advisors, "advisors cannot be null");
 			Assert.noNullElements(advisors, "advisors cannot contain null elements");
 			this.advisors.addAll(advisors);
-			this.aroundAdvisorChainBuilder.pushAll(advisors);
 			return this;
 		}
 
@@ -983,17 +946,26 @@ public ChatClientRequestSpec user(Consumer<PromptUserSpec> consumer) {
 		}
 
 		public CallResponseSpec call() {
-			BaseAdvisorChain advisorChain = aroundAdvisorChainBuilder.build();
+			BaseAdvisorChain advisorChain = buildAdvisorChain();
 			return new DefaultCallResponseSpec(toAdvisedRequest(this).toChatClientRequest(), advisorChain,
 					observationRegistry, observationConvention);
 		}
 
 		public StreamResponseSpec stream() {
-			BaseAdvisorChain advisorChain = aroundAdvisorChainBuilder.build();
+			BaseAdvisorChain advisorChain = buildAdvisorChain();
 			return new DefaultStreamResponseSpec(toAdvisedRequest(this).toChatClientRequest(), advisorChain,
 					observationRegistry, observationConvention);
 		}
 
+		private BaseAdvisorChain buildAdvisorChain() {
+			// At the stack bottom add the model call advisors.
+			// They play the role of the last advisors in the advisor chain.
+			this.advisors.add(ChatModelCallAdvisor.builder().chatModel(this.chatModel).build());
+			this.advisors.add(ChatModelStreamAdvisor.builder().chatModel(this.chatModel).build());
+
+			return DefaultAroundAdvisorChain.builder(this.observationRegistry).pushAll(this.advisors).build();
+		}
+
 	}
 
 	// Prompt

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

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2023-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.chat.client.advisor;
+
+import org.springframework.ai.chat.client.ChatClientResponse;
+import org.springframework.ai.chat.model.ChatResponse;
+import org.springframework.util.StringUtils;
+
+import java.util.function.Predicate;
+
+/**
+ * Utilities to work with advisors.
+ */
+public final class AdvisorUtils {
+
+	private AdvisorUtils() {
+	}
+
+	/**
+	 * Checks whether the provided {@link ChatClientResponse} contains a
+	 * {@link ChatResponse} with at least one result having a non-empty finish reason in
+	 * its metadata.
+	 */
+	public static Predicate<ChatClientResponse> onFinishReason() {
+		return chatClientResponse -> {
+			ChatResponse chatResponse = chatClientResponse.chatResponse();
+			return chatResponse != null && chatResponse.getResults() != null
+					&& chatResponse.getResults()
+						.stream()
+						.anyMatch(result -> result != null && result.getMetadata() != null
+								&& StringUtils.hasText(result.getMetadata().getFinishReason()));
+		};
+	}
+
+}