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

Class AIOrchestrator

java.lang.Object
com.vaadin.flow.component.ai.orchestrator.AIOrchestrator
public class AIOrchestrator extends Object
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).

Note: AIOrchestrator is not serializable. If your application uses session persistence, you will need to create a new orchestrator instance and pass the previously saved history via AIOrchestrator.Builder.withHistory(List, Map).

Author:
Vaadin Ltd

  • 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

    • 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