Package com.vaadin.flow.component.ai.orchestrator

Class AIOrchestrator

java.lang.Object
com.vaadin.flow.component.ai.orchestrator.AIOrchestrator
All Implemented Interfaces:
Serializable
public class AIOrchestrator extends Object implements Serializable
Orchestrator for AI-powered chat interfaces.

This class is a non-visual coordination engine that connects UI components with an LLM provider. It is not a UI component itself and should not be added to a layout or the UI. Instead, add the individual UI components (e.g. MessageInput, MessageList) to your layout and pass them to the orchestrator through its AIOrchestrator.Builder. The orchestrator then wires the components together and manages the LLM interaction behind the scenes.

It provides:

  • LLM integration
  • Component wiring (input, message list, file receiver)
  • Tool execution coordination
  • Programmatic invocation via prompt(String)

The orchestrator is configured via a fluent builder: 

 AIOrchestrator orchestrator = AIOrchestrator
         .builder(llmProvider, systemPrompt).withInput(messageInput) // optional
         .withMessageList(messageList) // optional
         .withFileReceiver(uploadManager) // optional
         .withTools(toolObj) // optional, for @Tool annotations
         .withUserName(userName) // optional
         .withAssistantName(assistantName) // optional
         .withResponseCompleteListener(e -> save(e.getResponse())) // optional
         .withHistory(savedHistory, savedAttachments) // optional, for restore
         .build();

The orchestrator tracks conversation history internally and delegates to the LLMProvider for the LLM's working memory. Use getHistory() to obtain a snapshot and AIOrchestrator.Builder.withHistory(List, Map) to restore conversation state (including attachments) across sessions. To persist history automatically after each exchange, use AIOrchestrator.Builder.withResponseCompleteListener(ResponseCompleteListener).

Serialization: The LLM provider and tool objects are not serialized (they are transient). After deserialization, call reconnect(LLMProvider) to restore transient dependencies and replay the conversation history onto the new provider: 

 orchestrator.reconnect(provider).withTools(toolObj) // optional
         .withAttachments(attachmentsByMsgId) // optional
         .apply();
The conversation history, UI component bindings, and listeners are preserved across serialization.

Author:
Vaadin Ltd
See Also:

  • Method Details

    • builder

      public static AIOrchestrator.Builder builder(LLMProvider provider, String systemPrompt)
      Creates a new builder for AIOrchestrator with a system prompt.
      Parameters:
      provider - the LLM provider
      systemPrompt - the system prompt for the LLM
      Returns:
      a new builder

    • prompt

      public void prompt(String userMessage)
      Sends a prompt to the AI orchestrator programmatically. This method allows sending prompts without requiring an input component.

      This is useful for scenarios where you want to trigger AI interaction from button clicks or other UI events without using a message input component.

      If a request is already being processed, this method will log a warning and return without processing the new prompt.

      Parameters:
      userMessage - the prompt to send to the AI
      Throws:
      IllegalStateException - if no UI context is available, or if the orchestrator needs to be reconnected after deserialization (see reconnect(LLMProvider))

    • reconnect

      public AIOrchestrator.Reconnector reconnect(LLMProvider provider)
      Returns a AIOrchestrator.Reconnector to restore transient dependencies after deserialization. The provider is required; tools and attachments are optional.

      Example usage: 

       orchestrator.reconnect(provider).withTools(toolObj)
         .withAttachments(attachmentsByMsgId).apply();

      Calling AIOrchestrator.Reconnector.apply() replays the existing conversation history onto the new provider so it has full context for subsequent prompts. The UI is not modified -- message list, input, and file receiver components retain their state across serialization.

      This method should only be called on a deserialized instance where the provider is null.

      Parameters:
      provider - the LLM provider to use, not null
      Returns:
      a reconnector for restoring additional transient dependencies
      Throws:
      NullPointerException - if provider is null
      IllegalStateException - if the orchestrator is already connected (provider is not null)

    • getHistory

      public List<ChatMessage> getHistory()
      Returns the conversation history.

      The returned list contains all user and assistant messages exchanged through this orchestrator. User messages include a ChatMessage.messageId() matching the ID provided to the AttachmentSubmitListener, which can be used to correlate with externally stored attachment data.

      Note: This method returns a point-in-time snapshot. If a streaming response is in progress, the snapshot may contain the user message without its corresponding assistant response. For automatic persistence, use AIOrchestrator.Builder.withResponseCompleteListener(ResponseCompleteListener) to be notified at the right time, then call getHistory() from that callback.

      Returns:
      an unmodifiable copy of the conversation history, never null