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

    • withController

      public AIOrchestrator.Builder withController(AIController controller)
      Sets the controller that provides framework-agnostic tools and lifecycle hooks to the orchestrator. The controller's tools are collected before each LLM request.
      Parameters:
      controller - the controller to set, not null
      Returns:
      this builder
      Throws:
      NullPointerException - if controller is null
      IllegalArgumentException - if any tool name is invalid

    • 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

    • withRequestListener

      public AIOrchestrator.Builder withRequestListener(RequestListener listener)
      Sets a listener that is called on every prompt, just before the LLM stream opens. The listener receives the user message, the assigned messageId, and the attachments included with the message (empty list when none). Same lifecycle moment as AIController.onRequest().

      Typical use: persist attachment data in your own storage keyed by messageId, so the same id can be used later to look the attachment up via AttachmentClickListener.AttachmentClickEvent.getMessageId() or when restoring conversation history via withHistory(List, Map).

      Parameters:
      listener - the listener to call on each prompt
      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 RequestListener.RequestEvent.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

    • withResponseListener

      public AIOrchestrator.Builder withResponseListener(ResponseListener listener)
      Sets a listener that is called once per turn when the assistant's stream has completed — successfully or with an error. This is the recommended hook for persisting conversation state (via AIOrchestrator.getHistory()), triggering follow-up actions, or surfacing errors to the user. Same lifecycle moment as AIController.onResponse(Throwable).

      On success the response text may be empty if the model emitted only tool calls or otherwise stopped without producing visible content. Such turns are still successful exchanges; check event.getResponse().isEmpty() if your listener should only react to text-bearing responses. Empty responses are not appended to the conversation history.

      On failure event.getError() carries the cause and the response text is empty or a partial stream that was received before the failure.

      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 history is restored via withHistory(List, Map).

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

    • withMetadata

      public AIOrchestrator.Builder withMetadata(com.vaadin.flow.function.SerializableSupplier<String> contextSupplier)
      Sets the supplier of free-form session context the LLM sees on every turn. The supplier is invoked once per turn on the UI thread when the request is being built.

      The supplier may return any string the application wants the LLM to have on hand — current date and time, the active tenant, the user's locale, the page the user is on, feature flags. Compose multiple pieces of context with plain string concatenation.

      If the supplier returns null or an empty/blank string, no context is added for that turn — useful for "context only when X" patterns. If the supplier throws, the turn is aborted via the normal error path: the assistant placeholder is updated to a generic error message, AIController.onResponse(Throwable) fires with the thrown exception, and the exception propagates to the caller of the prompt entry point.

      Passing null disables session context entirely, including the built-in default. By default, the orchestrator installs a supplier that yields the current date and time so the LLM can interpret relative date/time references ("show me sales from the past two months") without having to guess.

      The supplier runs on the UI thread, so it can read UI.getCurrent() and session-scoped state.

      Parameters:
      contextSupplier - supplier of the per-turn context string, or null to disable session context entirely
      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