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

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,51 @@
+/*
+ * 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"),
+	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,79 @@
+/*
+ * 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 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);
+		}
+
+	}
+
+}