Docs

Docs

AI Support

API: Java
Source: Java
Vaadin provides UI interfaces and an AI orchestrator for building AI-powered UIs with Vaadin, handling streaming, history, attachments, and tool calling.

Vaadin provides a set of UI interfaces and a coordination engine for building AI-powered UIs. The AIOrchestrator wires UI components to an LLM provider, handling streaming responses, conversation history, file attachments, and tool calling behind a simple builder API.

Note
Preview Feature

This is a preview version of AI support features. You need to enable it with the feature flag com.vaadin.experimental.aiComponents. Preview versions may lack some planned features, and breaking changes may be introduced in any Vaadin version. We encourage you to try it out and provide feedback to help us improve it.

Overview

The AI support module consists of four parts:

  • Orchestrator — AIOrchestrator is a non-visual coordination engine that connects UI components to an LLM provider. It has no DOM element and should not be added to a layout.

  • LLM Provider — plugs the orchestrator into any LLM framework. Spring AI and LangChain4j are built in via SpringAILLMProvider and LangChain4JLLMProvider; add others by implementing the LLMProvider interface.

  • Component interfaces — AIInput, AIMessageList, AIMessage, and AIFileReceiver define contracts for UI components that the orchestrator can work with. The builder also accepts standard Vaadin components (MessageInput, MessageList, UploadManager, Upload) directly.

  • Controllers — AIController is the framework-agnostic interface for contributing tools and lifecycle hooks to the orchestrator. Built-in controllers such as GridAIController and ChartAIController bring AI-powered data exploration to Grid and Chart, backed by a DatabaseProvider.

Add the UI components to your layout and pass them to the orchestrator through its builder. The orchestrator wires them together and manages the LLM interaction.

Basic Usage

Create an AI Orchestrator by passing an LLM provider and optional UI components to the builder. The following example uses a mock provider — replace it with a real provider such as SpringAILLMProvider or LangChain4JLLMProvider in production (see LLM Providers).

Open in a
new tab
Source code
AIOrchestratorBasic.java

When the user submits a message through the Message Input, the orchestrator automatically:

  1. Displays the user message in the Message List

  2. Sends the message to the LLM provider

  3. Streams the response tokens into the Message List in real time

  4. Records the exchange in the conversation history

By default, user messages are labeled "You" and assistant messages are labeled "Assistant". Use withUserName() and withAssistantName() on the builder to customize these display names.

Tip
Always Provide a System Prompt
A system prompt is strongly recommended. Without one, the LLM has no guidance beyond your tool descriptions and may behave inconsistently from turn to turn. Use it to set the assistant’s role, tone, constraints, and any domain-specific rules — for example, "You are a helpful customer-support assistant for an online bookstore. Keep answers short and cite order numbers verbatim."
Note
One Orchestrator per Instance
Each LLMProvider, MessageList (or AIMessageList), MessageInput (or AIInput), file receiver, and AIController may be passed to only one AIOrchestrator. Attempting to share an instance across two orchestrators throws IllegalStateException at build time. When building multi-view or dashboard applications, create a separate set of components — including a dedicated provider — for each orchestrator.

Server Push

Streaming mode pushes partial responses to the UI as tokens arrive. This requires server push to be enabled. Annotate your application shell with @Push:

Source code
Java
@Push
@SpringBootApplication
public class Application implements AppShellConfigurator {
}
Tip
 Synchronous mode does not require push. If push is not available in your environment, disable streaming on the provider. A warning is logged at runtime if push is not enabled when using streaming mode.

Topics

Component Interfaces
AI interface contracts for input, message list, message, and file receiver components used by the AIOrchestrator.
LLM Providers
Connect the AIOrchestrator to Spring AI, LangChain4j, or a custom LLM framework using the LLMProvider interface.
File Attachments
Enable file uploads in the AIOrchestrator to send attachments to the LLM with user prompts.
Tool Calling & Programmatic Prompts
Register tool objects for LLM invocation and send prompts programmatically without a Message Input component.
Controllers
Extend the AIOrchestrator with reusable, framework-agnostic tools and lifecycle hooks using the AIController interface.
Conversation History & Session Persistence
Persist and restore conversation history, and reconnect the AIOrchestrator after session deserialization.
AI-Powered Grid
Use GridAIController to let users populate a Grid from the application database using natural language.
AI-Powered Chart
Use ChartAIController to let users build and update Highcharts visualizations from the application database using natural language.
Component Usage recommendations

Message Input

Text input for user messages. Pass to the orchestrator with withInput().

Message List

Displays messages. Pass to the orchestrator with withMessageList().

Upload

File uploads via UploadManager. Pass to the orchestrator with withFileReceiver().

Grid

Populated from the application database via natural-language requests. See AI-Powered Grid.

Charts

Built and updated from the application database via natural-language requests. See AI-Powered Chart.

Updated –