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

Class AIOrchestrator.Builder

java.lang.Object
com.vaadin.flow.component.ai.orchestrator.AIOrchestrator.Builder
Enclosing class:
AIOrchestrator
public static class AIOrchestrator.Builder extends Object
Builder for configuring and creating an AIOrchestrator instance.

The builder requires an LLMProvider and a system prompt. All other settings are optional:

Both Flow components (MessageInput, MessageList, UploadManager, Upload) and custom implementations of the AI interfaces (AIInput, AIMessageList, AIFileReceiver) are accepted.

  • Method Details

    • withMessageList

      public AIOrchestrator.Builder withMessageList(AIMessageList messageList)
      Sets the message list component.
      Parameters:
      messageList - the message list
      Returns:
      this builder

    • withMessageList

      public AIOrchestrator.Builder withMessageList(com.vaadin.flow.component.messages.MessageList messageList)
      Sets the message list component using a Flow MessageList component.
      Parameters:
      messageList - the Flow MessageList component
      Returns:
      this builder

    • withInput

      public AIOrchestrator.Builder withInput(AIInput input)
      Sets the input component.
      Parameters:
      input - the input component
      Returns:
      this builder

    • withInput

      public AIOrchestrator.Builder withInput(com.vaadin.flow.component.messages.MessageInput messageInput)
      Sets the input component using a Flow MessageInput component.
      Parameters:
      messageInput - the Flow MessageInput component
      Returns:
      this builder

    • withFileReceiver

      public AIOrchestrator.Builder withFileReceiver(AIFileReceiver fileReceiver)
      Sets the file receiver component for file uploads.
      Parameters:
      fileReceiver - the file receiver
      Returns:
      this builder

    • withFileReceiver

      public AIOrchestrator.Builder withFileReceiver(com.vaadin.flow.component.upload.UploadManager uploadManager)
      Sets the file receiver component using a Flow UploadManager. The provided manager should not have an UploadHandler set beforehand.
      Parameters:
      uploadManager - the Flow UploadManager
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the UploadManager already has an UploadHandler

    • withFileReceiver

      public AIOrchestrator.Builder withFileReceiver(com.vaadin.flow.component.upload.Upload upload)
      Sets the file receiver component using a Flow Upload component. The provided upload should not have an UploadHandler or a Receiver set beforehand.
      Parameters:
      upload - the Flow Upload component
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the Upload already has an UploadHandler or a Receiver

    • withTools

      public AIOrchestrator.Builder withTools(Object... tools)
      Sets the objects containing vendor-specific tool-annotated methods that will be available to the LLM.

      For LangChain4j, use @dev.langchain4j.agent.tool.Tool. For Spring AI, use @org.springframework.ai.tool.annotation.Tool.

      Parameters:
      tools - the objects containing tool methods
      Returns:
      this builder

    • withUserName

      public AIOrchestrator.Builder withUserName(String userName)
      Sets the display name for user messages in the message list.

      This name is shown as the author of messages sent by the user. If not set, defaults to "You".

      Parameters:
      userName - the display name for user messages, not null
      Returns:
      this builder

    • withAssistantName

      public AIOrchestrator.Builder withAssistantName(String assistantName)
      Sets the display name for AI assistant messages in the message list.

      This name is shown as the author of messages generated by the AI. If not set, defaults to "Assistant".

      Parameters:
      assistantName - the display name for AI messages, not null
      Returns:
      this builder

    • withAttachmentSubmitListener

      public AIOrchestrator.Builder withAttachmentSubmitListener(AttachmentSubmitListener listener)
      Sets a listener that is called when a message with attachments is submitted to the LLM provider. This allows you to store attachment data in your own storage. The listener receives a unique message ID that can later be used to identify the attachments when they are clicked or when restoring conversation history via withHistory(List, Map).
      Parameters:
      listener - the listener to call on attachment submit
      Returns:
      this builder

    • withAttachmentClickListener

      public AIOrchestrator.Builder withAttachmentClickListener(AttachmentClickListener listener)
      Sets a listener that is called when an attachment in the message list is clicked. The listener receives the message ID and attachment index, allowing you to retrieve attachment data from your own storage using the same message ID provided in AttachmentSubmitListener.AttachmentSubmitEvent.getMessageId().

      Note: This listener requires a message list to be configured via withMessageList(MessageList). If no message list is set, the listener will have no effect.

      Parameters:
      listener - the listener to call on attachment click
      Returns:
      this builder

    • withResponseCompleteListener

      public AIOrchestrator.Builder withResponseCompleteListener(ResponseCompleteListener listener)
      Sets a listener that is called after each successful exchange — when the assistant's response has been fully streamed and added to the conversation history. This is the recommended hook for persisting conversation state (via AIOrchestrator.getHistory()), triggering follow-up actions, or updating UI elements.

      The listener is called from a background thread (Reactor scheduler). It is safe to perform blocking I/O (e.g. database writes) directly. To update Vaadin UI components from this listener, use ui.access().

      The listener is not called when the LLM response fails, times out, or produces an empty response, nor when history is restored via withHistory(List, Map).

      Parameters:
      listener - the listener to call after each successful exchange
      Returns:
      this builder

    • withHistory

      public AIOrchestrator.Builder withHistory(List<ChatMessage> history, Map<String,List<AIAttachment>> attachmentsByMessageId)
      Sets the conversation history and associated attachments to restore when the orchestrator is built. This restores the LLM provider's conversation context (including multimodal content), the message list UI with attachment thumbnails, and the internal message ID mappings for attachment click handling.

      The attachment map is keyed by ChatMessage.messageId() and contains the list of AIAttachment objects for each message. Messages whose IDs are not in the map are restored as text-only. The attachments are used once during initialization and are not retained by the orchestrator. Pass Collections.emptyMap() if there are no attachments to restore.

      Parameters:
      history - the conversation history to restore, not null
      attachmentsByMessageId - a map from message ID to attachment list, not null
      Returns:
      this builder

    • build

      public AIOrchestrator build()
      Builds the orchestrator.
      Returns:
      the configured orchestrator