Make ChatClient and Advisor APIs more robust - Part 1

- Introduce “ChatClientRequest” and “ChatClientResponse” for propagating requests/responses in a ChatClient advisor chain.
- Structure a Prompt at the beginning of the chain, to ensure a consistent view across execution chain and observations. Any template is rendered at the beginning so that every advisor doesn’t have to do it again.
- Improve observations to include the complete view of the prompt messages, instead of only considering userText and systemText.
- Remove legacy “around” advisor type concept.
- Keep backward compatibility for AdvisedRequest, AdvisedResponse, and legacy Advisor APIs.

Relates to gh-2655

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

Author: ThomasVitale

models/spring-ai-anthropic/src/test/java/org/springframework/ai/anthropic/client/AnthropicChatClientIT.java

@@ -42,6 +42,7 @@
 import org.springframework.ai.chat.model.ChatResponse;
 import org.springframework.ai.converter.BeanOutputConverter;
 import org.springframework.ai.converter.ListOutputConverter;
+import org.springframework.ai.test.CurlyBracketEscaper;
 import org.springframework.ai.tool.function.FunctionToolCallback;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Value;
@@ -189,7 +190,7 @@ void beanStreamOutputConverterRecords() {
 				.user(u -> u
 						.text("Generate the filmography of 5 movies for Tom Hanks. " + System.lineSeparator()
 								+ "{format}")
-						.param("format", outputConverter.getFormat()))
+						.param("format", CurlyBracketEscaper.escapeCurlyBrackets(outputConverter.getFormat())))
 				.stream()
 				.content();
 

models/spring-ai-azure-openai/src/test/java/org/springframework/ai/azure/openai/AzureOpenAiChatClientIT.java

@@ -31,6 +31,7 @@
 import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
 import org.springframework.ai.chat.model.ChatResponse;
 import org.springframework.ai.converter.BeanOutputConverter;
+import org.springframework.ai.test.CurlyBracketEscaper;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.boot.SpringBootConfiguration;
@@ -83,7 +84,7 @@ void beanStreamOutputConverterRecords() {
 				.user(u -> u
 						.text("Generate the filmography of 5 movies for Tom Hanks. " + System.lineSeparator()
 								+ "{format}")
-						.param("format", outputConverter.getFormat()))
+						.param("format", CurlyBracketEscaper.escapeCurlyBrackets(outputConverter.getFormat())))
 				.stream()
 				.chatResponse();
 

models/spring-ai-bedrock-converse/src/test/java/org/springframework/ai/bedrock/converse/BedrockConverseChatClientIT.java

@@ -37,6 +37,7 @@
 import org.springframework.ai.converter.BeanOutputConverter;
 import org.springframework.ai.converter.ListOutputConverter;
 import org.springframework.ai.model.tool.ToolCallingChatOptions;
+import org.springframework.ai.test.CurlyBracketEscaper;
 import org.springframework.ai.tool.function.FunctionToolCallback;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Value;
@@ -182,7 +183,7 @@ void beanStreamOutputConverterRecords() {
 				.user(u -> u
 						.text("Generate the filmography of 5 movies for Tom Hanks. " + System.lineSeparator()
 								+ "{format}")
-						.param("format", outputConverter.getFormat()))
+						.param("format", CurlyBracketEscaper.escapeCurlyBrackets(outputConverter.getFormat())))
 				.stream()
 				.chatResponse();
 

models/spring-ai-mistral-ai/src/test/java/org/springframework/ai/mistralai/MistralAiChatClientIT.java

@@ -28,12 +28,14 @@
 import reactor.core.publisher.Flux;
 
 import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
 import org.springframework.ai.chat.messages.UserMessage;
 import org.springframework.ai.chat.model.ChatResponse;
 import org.springframework.ai.converter.BeanOutputConverter;
 import org.springframework.ai.converter.ListOutputConverter;
 import org.springframework.ai.mistralai.api.MistralAiApi;
 import org.springframework.ai.mistralai.api.MistralAiApi.ChatCompletionRequest.ToolChoice;
+import org.springframework.ai.test.CurlyBracketEscaper;
 import org.springframework.ai.tool.function.FunctionToolCallback;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Value;
@@ -198,10 +200,11 @@ void beanStreamOutputConverterRecords() {
 		// @formatter:off
 		Flux<String> chatResponse = ChatClient.create(this.chatModel)
 				.prompt()
+				.advisors(new SimpleLoggerAdvisor())
 				.user(u -> u
 						.text("Generate the filmography of 5 movies for Tom Hanks. " + System.lineSeparator()
 								+ "{format}")
-						.param("format", outputConverter.getFormat()))
+						.param("format", CurlyBracketEscaper.escapeCurlyBrackets(outputConverter.getFormat())))
 				.stream()
 				.content();
 

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/client/OpenAiChatClientIT.java

@@ -43,6 +43,7 @@
 import org.springframework.ai.openai.api.OpenAiApi.ChatCompletionRequest.AudioParameters;
 import org.springframework.ai.openai.api.tool.MockWeatherService;
 import org.springframework.ai.openai.testutils.AbstractIT;
+import org.springframework.ai.test.CurlyBracketEscaper;
 import org.springframework.ai.tool.function.FunctionToolCallback;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.boot.test.context.SpringBootTest;
@@ -220,7 +221,7 @@ void beanStreamOutputConverterRecords() {
 				.user(u -> u
 						.text("Generate the filmography of 5 movies for Tom Hanks. " + System.lineSeparator()
 								+ "{format}")
-						.param("format", outputConverter.getFormat()))
+						.param("format", CurlyBracketEscaper.escapeCurlyBrackets(outputConverter.getFormat())))
 				.stream()
 				.chatResponse();
 

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

@@ -156,6 +156,8 @@ interface CallResponseSpec {
 		@Nullable
 		<T> T entity(Class<T> type);
 
+		ChatClientResponse chatClientResponse();
+
 		@Nullable
 		ChatResponse chatResponse();
 
@@ -172,6 +174,8 @@ interface CallResponseSpec {
 
 	interface StreamResponseSpec {
 
+		Flux<ChatClientResponse> chatClientResponse();
+
 		Flux<ChatResponse> chatResponse();
 
 		Flux<String> content();

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

@@ -0,0 +1,52 @@
+/*
+ * 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;
+
+/**
+ * Common attributes used in {@link ChatClient} context.
+ *
+ * @author Thomas Vitale
+ * @since 1.0.0
+ */
+public enum ChatClientAttributes {
+
+	//@formatter:off
+
+	@Deprecated // Only for backward compatibility until the next release.
+	ADVISORS("spring.ai.chat.client.advisors"),
+	@Deprecated // Only for backward compatibility until the next release.
+	CHAT_MODEL("spring.ai.chat.client.model"),
+	@Deprecated // Only for backward compatibility until the next release.
+	OUTPUT_FORMAT("spring.ai.chat.client.output.format"),
+	@Deprecated // Only for backward compatibility until the next release.
+	USER_PARAMS("spring.ai.chat.client.user.params"),
+	@Deprecated // Only for backward compatibility until the next release.
+	SYSTEM_PARAMS("spring.ai.chat.client.system.params");
+
+	//@formatter:on
+
+	private final String key;
+
+	ChatClientAttributes(String key) {
+		this.key = key;
+	}
+
+	public String getKey() {
+		return key;
+	}
+
+}

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

@@ -0,0 +1,83 @@
+/*
+ * 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;
+
+import org.springframework.ai.chat.prompt.Prompt;
+import org.springframework.util.Assert;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Represents a request processed by a {@link ChatClient} that ultimately is used to build
+ * a {@link Prompt} to be sent to an AI model.
+ *
+ * @param prompt The prompt to be sent to the AI model
+ * @param context The contextual data through the execution chain
+ * @author Thomas Vitale
+ * @since 1.0.0
+ */
+public record ChatClientRequest(Prompt prompt, Map<String, Object> context) {
+
+	public ChatClientRequest {
+		Assert.notNull(prompt, "prompt cannot be null");
+		Assert.notNull(context, "context cannot be null");
+		Assert.noNullElements(context.keySet(), "context keys cannot be null");
+	}
+
+	public Builder mutate() {
+		return new Builder().prompt(this.prompt).context(this.context);
+	}
+
+	public static Builder builder() {
+		return new Builder();
+	}
+
+	public static final class Builder {
+
+		private Prompt prompt;
+
+		private Map<String, Object> context = new HashMap<>();
+
+		private Builder() {
+		}
+
+		public Builder prompt(Prompt prompt) {
+			Assert.notNull(prompt, "prompt cannot be null");
+			this.prompt = prompt;
+			return this;
+		}
+
+		public Builder context(Map<String, Object> context) {
+			Assert.notNull(context, "context cannot be null");
+			this.context.putAll(context);
+			return this;
+		}
+
+		public Builder context(String key, Object value) {
+			Assert.notNull(key, "key cannot be null");
+			this.context.put(key, value);
+			return this;
+		}
+
+		public ChatClientRequest build() {
+			return new ChatClientRequest(prompt, context);
+		}
+
+	}
+
+}

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

@@ -0,0 +1,77 @@
+/*
+ * 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;
+
+import org.springframework.ai.chat.model.ChatResponse;
+import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Represents a response returned by a {@link ChatClient}.
+ *
+ * @param chatResponse The response returned by the AI model
+ * @param context The contextual data propagated through the execution chain
+ * @author Thomas Vitale
+ * @since 1.0.0
+ */
+public record ChatClientResponse(@Nullable ChatResponse chatResponse, Map<String, Object> context) {
+
+	public ChatClientResponse {
+		Assert.notNull(context, "context cannot be null");
+		Assert.noNullElements(context.keySet(), "context keys cannot be null");
+	}
+
+	public static Builder builder() {
+		return new Builder();
+	}
+
+	public static class Builder {
+
+		private ChatResponse chatResponse;
+
+		private Map<String, Object> context = new HashMap<>();
+
+		private Builder() {
+		}
+
+		public Builder chatResponse(ChatResponse chatResponse) {
+			this.chatResponse = chatResponse;
+			return this;
+		}
+
+		public Builder context(Map<String, Object> context) {
+			Assert.notNull(context, "context cannot be null");
+			this.context.putAll(context);
+			return this;
+		}
+
+		public Builder context(String key, Object value) {
+			Assert.notNull(key, "key cannot be null");
+			this.context.put(key, value);
+			return this;
+		}
+
+		public ChatClientResponse build() {
+			return new ChatClientResponse(this.chatResponse, this.context);
+		}
+
+	}
+
+}