Interface ChatExecutor

public interface ChatExecutor

Generic executor interface that defines a chat interaction

When built with an event listener registrar, the built-in executors fire an AiServiceRequestIssuedEvent for every request they send. They fire an AiServiceResponseReceivedEvent only for the methods that take chat messages (used for output guardrail reprompts): for execute() and executeAsync(), the caller fires it.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	ChatExecutor.AbstractBuilder<T extends ChatExecutor.AbstractBuilder<T>>	An abstract base-builder class for constructing instances of ChatExecutor.
static class	ChatExecutor.StreamingToSynchronousBuilder	StreamingToSynchronousBuilder for constructing instances of ChatExecutor.
static class	ChatExecutor.SynchronousBuilder	SynchronousBuilder for constructing instances of ChatExecutor.

Method Summary

Modifier and Type	Method	Description
static ChatExecutor.SynchronousBuilder	builder(ChatModel chatModel)	Creates a new ChatExecutor.SynchronousBuilder instance for constructing ChatExecutor objects that perform synchronous chat requests.
static ChatExecutor.StreamingToSynchronousBuilder	builder(StreamingChatModel streamingChatModel)	Creates a new ChatExecutor.StreamingToSynchronousBuilder instance for constructing ChatExecutor objects that perform streaming chat requests.
default ChatExchange	exchange(List<ChatMessage> chatMessages)	Like execute(List), but also returns the request that produced the response.
default CompletableFuture<ChatExchange>	exchangeAsync(List<ChatMessage> chatMessages)	Non-blocking counterpart of exchange(List).
ChatResponse	execute()	Execute a chat request
ChatResponse	execute(List<ChatMessage> chatMessages)	Executes a chat request using the provided chat messages
default CompletableFuture<ChatResponse>	executeAsync()	Non-blocking counterpart of execute().
default CompletableFuture<ChatResponse>	executeAsync(List<ChatMessage> chatMessages)	Non-blocking counterpart of execute(List).

Method Details

execute

ChatResponse execute()

Execute a chat request

Returns:

The response

execute

ChatResponse execute(List<ChatMessage> chatMessages)

Executes a chat request using the provided chat messages

Parameters:

chatMessages - The chat messages containing the context of the conversation. It provides the history of messages required for proper interaction with the chat model

Returns:

A response object containing the AI's response and additional metadata.

executeAsync

@Experimental
default CompletableFuture<ChatResponse> executeAsync()

Non-blocking counterpart of execute().

The default implementation returns a failed future carrying AsyncNotSupportedException; the built-in executors override it to call the model without blocking (via the async/reactive model APIs). Used by output-guardrail reprompts on the non-blocking AI Service paths. Consistent with ChatModel#doChatAsync and the other async defaults, a blocking executor is not silently run on the calling thread.

Returns:

a CompletableFuture that completes with the response

Since:

1.20.0

executeAsync

@Experimental
default CompletableFuture<ChatResponse> executeAsync(List<ChatMessage> chatMessages)

Non-blocking counterpart of execute(List).

The default implementation returns a failed future carrying AsyncNotSupportedException; the built-in executors override it to call the model without blocking (via the async/reactive model APIs). Used by output-guardrail reprompts on the non-blocking AI Service paths. Consistent with ChatModel#doChatAsync and the other async defaults, a blocking executor is not silently run on the calling thread.

Parameters:

chatMessages - The chat messages containing the context of the conversation.

Returns:

a CompletableFuture that completes with the response

Since:

1.20.0

exchange

@Experimental
default ChatExchange exchange(List<ChatMessage> chatMessages)

Like execute(List), but also returns the request that produced the response. When the response is the result of a tool-calling loop, the request is the last one sent to the model, with the tool calls and tool results of all rounds.

The default implementation calls execute(List) and returns null as the request, because the request that the executor sent is not known.

Parameters:

chatMessages - The chat messages containing the context of the conversation.

Returns:

the response and the request that produced it; ChatExchange.request() is null when the request is not known

Since:

1.23.0

exchangeAsync

@Experimental
default CompletableFuture<ChatExchange> exchangeAsync(List<ChatMessage> chatMessages)

Non-blocking counterpart of exchange(List).

The default implementation calls executeAsync(List) and returns null as the request, because the request that the executor sent is not known.

Parameters:

chatMessages - The chat messages containing the context of the conversation.

Returns:

a CompletableFuture that completes with the request and the response

Since:

1.23.0

builder

static ChatExecutor.SynchronousBuilder builder(ChatModel chatModel)

Creates a new ChatExecutor.SynchronousBuilder instance for constructing ChatExecutor objects that perform synchronous chat requests.

Returns:

A new ChatExecutor.SynchronousBuilder instance to configure and build a ChatExecutor.

builder

static ChatExecutor.StreamingToSynchronousBuilder builder(StreamingChatModel streamingChatModel)

Creates a new ChatExecutor.StreamingToSynchronousBuilder instance for constructing ChatExecutor objects that perform streaming chat requests.

Returns:

A new ChatExecutor.StreamingToSynchronousBuilder instance to configure and build a ChatExecutor.