tessl/maven-org-springframework-ai--spring-ai-client-chat
Spring AI Chat Client provides a fluent API for building AI-powered applications with LLMs, supporting advisors, streaming, structured outputs, and conversation memory
chat-client-api.mddocs/reference/
ChatClient API
The ChatClient interface is the main entry point for interacting with AI language models. It provides a fluent, builder-based API for constructing and executing chat requests.
Imports
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import io.micrometer.observation.ObservationRegistry;
import org.springframework.lang.Nullable;Creating ChatClient Instances
Simple Creation
static ChatClient create(ChatModel chatModel);Creates a ChatClient with default settings using the provided ChatModel.
Example:
ChatModel chatModel = // ... obtain from Spring context
ChatClient client = ChatClient.create(chatModel);Creation with Observability
static ChatClient create(
ChatModel chatModel,
ObservationRegistry observationRegistry
);Creates a ChatClient with observability support for metrics and tracing.
Parameters:
chatModel- The ChatModel to use for LLM interactionsobservationRegistry- Micrometer ObservationRegistry for metrics
Example:
ChatClient client = ChatClient.create(chatModel, observationRegistry);Creation with Full Observability Configuration
static ChatClient create(
ChatModel chatModel,
ObservationRegistry observationRegistry,
@Nullable ChatClientObservationConvention chatClientObservationConvention,
@Nullable AdvisorObservationConvention advisorObservationConvention
);Creates a ChatClient with custom observation conventions for both client and advisor metrics.
Parameters:
chatModel- The ChatModel to useobservationRegistry- ObservationRegistry for metricschatClientObservationConvention- Custom convention for client observations (nullable)advisorObservationConvention- Custom convention for advisor observations (nullable)
Using Builder
static ChatClient.Builder builder(ChatModel chatModel);
static ChatClient.Builder builder(
ChatModel chatModel,
ObservationRegistry observationRegistry,
@Nullable ChatClientObservationConvention chatClientObservationConvention,
@Nullable AdvisorObservationConvention advisorObservationConvention
);Returns a Builder instance for configuring a ChatClient with defaults. The second overload allows full control over observability configuration.
Parameters (full signature):
chatModel- The ChatModel to useobservationRegistry- ObservationRegistry for metricschatClientObservationConvention- Custom convention for client observations (nullable)advisorObservationConvention- Custom convention for advisor observations (nullable)
Example:
ChatClient client = ChatClient.builder(chatModel)
.defaultSystem("You are a helpful assistant")
.defaultAdvisors(someAdvisor)
.build();Starting Requests
Basic Prompt
ChatClient.ChatClientRequestSpec prompt();Start building a request with an empty prompt. Returns a ChatClientRequestSpec for configuring the request.
Example:
String response = chatClient
.prompt()
.user("Hello, AI!")
.call()
.content();Text Prompt
ChatClient.ChatClientRequestSpec prompt(String text);Start building a request with the provided text as the user message.
Parameters:
text- The user message text
Returns: ChatClientRequestSpec for further configuration
Example:
String response = chatClient
.prompt("What is Spring Boot?")
.call()
.content();Prompt Object
ChatClient.ChatClientRequestSpec prompt(Prompt prompt);Start building a request with a pre-constructed Prompt object containing messages and options.
Parameters:
prompt- A fully configured Prompt object
Returns: ChatClientRequestSpec for further configuration
Example:
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.messages.UserMessage;
Prompt prompt = new Prompt(new UserMessage("Explain AI"));
String response = chatClient
.prompt(prompt)
.call()
.content();Mutating Existing Client
ChatClient.Builder mutate();Creates a new Builder pre-populated with the current client's configuration. Useful for creating variants of an existing client.
Returns: Builder instance with current configuration
Example:
ChatClient baseClient = ChatClient.builder(chatModel)
.defaultSystem("You are helpful")
.build();
ChatClient specializedClient = baseClient.mutate()
.defaultSystem("You are a code expert")
.build();Builder Interface
The ChatClient.Builder interface provides methods for configuring default settings.
interface Builder {
// Default advisors
Builder defaultAdvisors(Advisor... advisors);
Builder defaultAdvisors(Consumer<AdvisorSpec> advisorSpecConsumer);
Builder defaultAdvisors(List<Advisor> advisors);
// Default system message
Builder defaultSystem(String text);
Builder defaultSystem(Resource text, Charset charset);
Builder defaultSystem(Resource resource);
Builder defaultSystem(Consumer<PromptSystemSpec> systemSpecConsumer);
// Default user message
Builder defaultUser(String text);
Builder defaultUser(Resource text, Charset charset);
Builder defaultUser(Resource resource);
Builder defaultUser(Consumer<PromptUserSpec> userSpecConsumer);
// Default tools
Builder defaultToolNames(String... toolNames);
Builder defaultTools(Object... toolObjects);
Builder defaultToolCallbacks(ToolCallback... toolCallbacks);
Builder defaultToolCallbacks(List<ToolCallback> toolCallbacks);
Builder defaultToolCallbacks(ToolCallbackProvider... toolCallbackProviders);
Builder defaultToolContext(Map<String, Object> toolContext);
// Default options
Builder defaultOptions(ChatOptions chatOptions);
// Template renderer
Builder defaultTemplateRenderer(TemplateRenderer templateRenderer);
// Cloning
Builder clone();
// Build
ChatClient build();
}Default Advisors
Configure advisors that will be applied to all requests unless overridden.
Example:
ChatClient client = ChatClient.builder(chatModel)
.defaultAdvisors(
MessageChatMemoryAdvisor.builder(chatMemory).build(),
SimpleLoggerAdvisor.builder().build()
)
.build();Default System Message
Set a system message that will be included in all requests.
Text:
Builder defaultSystem(String text);From Resource:
Builder defaultSystem(Resource resource);With Consumer:
Builder defaultSystem(Consumer<PromptSystemSpec> systemSpecConsumer);Example:
ChatClient client = ChatClient.builder(chatModel)
.defaultSystem("You are an expert Java developer")
.build();
// Or with parameters
ChatClient client = ChatClient.builder(chatModel)
.defaultSystem(spec -> spec
.text("You are an expert in {language}")
.param("language", "Java")
)
.build();Default User Message
Set a user message template that will be included in all requests.
Example:
ChatClient client = ChatClient.builder(chatModel)
.defaultUser("Please answer in a professional tone")
.build();Default Tools
Configure tools available for all requests.
Builder defaultToolNames(String... toolNames);
Builder defaultTools(Object... toolObjects);
Builder defaultToolCallbacks(ToolCallback... toolCallbacks);
Builder defaultToolCallbacks(List<ToolCallback> toolCallbacks);
Builder defaultToolCallbacks(ToolCallbackProvider... toolCallbackProviders);
Builder defaultToolContext(Map<String, Object> toolContext);Example:
import org.springframework.ai.tool.ToolCallback;
ToolCallback weatherTool = // ... define tool
ChatClient client = ChatClient.builder(chatModel)
.defaultToolCallbacks(weatherTool)
.build();Default Options
Set ChatOptions (model parameters like temperature, maxTokens) for all requests.
Builder defaultOptions(ChatOptions chatOptions);Example:
import org.springframework.ai.chat.options.ChatOptions;
import org.springframework.ai.chat.options.ChatOptionsBuilder;
ChatClient client = ChatClient.builder(chatModel)
.defaultOptions(ChatOptionsBuilder.builder()
.withModel("gpt-4")
.withTemperature(0.7)
.withMaxTokens(2000)
.build())
.build();Observability Configuration
Observability is configured through the builder factory method, not through Builder instance methods. See Creating ChatClient Instances above for how to configure observability.
Complete Example
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
import org.springframework.ai.chat.memory.InMemoryChatMemory;
import org.springframework.ai.chat.options.ChatOptionsBuilder;
// Build a fully configured client
ChatClient client = ChatClient.builder(chatModel)
.defaultSystem("You are a helpful AI assistant specialized in Java and Spring")
.defaultAdvisors(
MessageChatMemoryAdvisor.builder(new InMemoryChatMemory()).build(),
SimpleLoggerAdvisor.builder().build()
)
.defaultOptions(ChatOptionsBuilder.builder()
.withTemperature(0.7)
.withMaxTokens(1000)
.build())
.observationRegistry(observationRegistry)
.build();
// Use the client
String answer = client
.prompt("Explain dependency injection")
.call()
.content();Integration with Spring Boot
When using Spring Boot with Spring AI auto-configuration, you can customize the auto-configured ChatClient using ChatClientCustomizer:
import org.springframework.ai.chat.client.ChatClientCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
class ChatClientConfiguration {
@Bean
ChatClientCustomizer customizer() {
return builder -> builder
.defaultSystem("Custom system prompt")
.defaultAdvisors(/* advisors */);
}
}