> Markdown version of [AI Integration](https://vaadin.com/docs/latest/flow/ai-support). Section index: [llms.txt](https://vaadin.com/docs/latest/flow/llms.txt)

# AI Integration (since V25.1)

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 integration features. You need to enable it with the [feature flag](https://vaadin.com/docs/latest/flow/configuration/feature-flags.md) `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 in the Forum](https://vaadin.com/forum/) so that we can make it stable. You can report bugs and request additional features on [GitHub](https://github.com/vaadin/flow-components/issues/new/choose).

## <a id="overview"></a>Overview

AI integration 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 bring AI-powered data exploration to `Grid` and `Chart` through `GridAIController` and `ChartAIController` (backed by a `DatabaseProvider`), and form-filling to any layout containing input fields through `FormAIController`. The built-in controllers are a commercial feature; see [Controllers](https://vaadin.com/docs/latest/flow/ai-support/controllers.md).

The orchestrator, LLM providers, component interfaces, and the `AIController` interface are free and open source (the `vaadin-ai-core-flow` module). The built-in Grid, Chart, and Form controllers are part of the commercial `vaadin-ai-extensions-flow` module and require a commercial Vaadin subscription.

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.

## <a id="basic-usage"></a>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](https://vaadin.com/docs/latest/flow/ai-support/llm-providers.md)).

**Flow** — `AIOrchestratorBasic.java`

```java
MessageList messageList = new MessageList();
messageList.setMarkdown(true);
MessageInput messageInput = new MessageInput();

LLMProvider provider = new MockLLMProvider();

AIOrchestrator.builder(provider, "You are a helpful assistant.")
        .withMessageList(messageList).withInput(messageInput).build();

add(messageList, messageInput);
```

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: Render Responses as Markdown**
>
> LLMs answer in Markdown, but [Message List](https://vaadin.com/docs/latest/components/message-list.md) renders plain text unless asked otherwise, and the orchestrator doesn’t change that. Call `setMarkdown(true)` on the list so that headings, lists, code blocks, and links come out as rich text instead of raw syntax.

> **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.

## <a id="server-push"></a>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`:

```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 when neither automatic push nor polling is active while using streaming mode. Note that a synchronous provider runs the whole exchange in the request that triggered it, which blocks the UI until the response is complete — see [Background Execution](https://vaadin.com/docs/latest/flow/ai-support/llm-providers.md#background-execution) for keeping the UI responsive.

## <a id="topics"></a>Topics

- [Component Interfaces](https://vaadin.com/docs/latest/flow/ai-support/component-interfaces.md): AI interface contracts for input, message list, message, and file receiver components used by the AIOrchestrator.
- [LLM Providers](https://vaadin.com/docs/latest/flow/ai-support/llm-providers.md): Connect the AIOrchestrator to Spring AI, LangChain4j, or a custom LLM framework using the LLMProvider interface.
- [File Attachments](https://vaadin.com/docs/latest/flow/ai-support/file-attachments.md): Enable file uploads in the AIOrchestrator to send attachments to the LLM with user prompts.
- [Session Context](https://vaadin.com/docs/latest/flow/ai-support/session-context.md): Pass per-turn ambient information -- date and time, tenant, locale, page state -- to the LLM through the AIOrchestrator.
- [Request Interception](https://vaadin.com/docs/latest/flow/ai-support/request-interception.md): Validate, sanitize, or replace user prompts and attachments -- or reject them -- before the AIOrchestrator sends anything to the LLM.
- [Request & Response Listeners](https://vaadin.com/docs/latest/flow/ai-support/listeners.md): Observe each prompt and its outcome with orchestrator-level listeners, including the finish reason and token usage of each LLM turn.
- [Tool Calling & Programmatic Prompts](https://vaadin.com/docs/latest/flow/ai-support/tool-calling.md): Register tool objects for LLM invocation and send prompts programmatically without a Message Input component.
- [Controllers](https://vaadin.com/docs/latest/flow/ai-support/controllers.md): Extend the AIOrchestrator with reusable, framework-agnostic tools and lifecycle hooks using the AIController interface.
- [Conversation History & Session Persistence](https://vaadin.com/docs/latest/flow/ai-support/conversation-history.md): Persist and restore conversation history, and reconnect the AIOrchestrator after session deserialization.
- [AI-Generated Grids](https://vaadin.com/docs/latest/flow/ai-support/ai-powered-grid.md): Use GridAIController to let users populate a Grid from the application database using natural language.
- [AI-Generated Charts](https://vaadin.com/docs/latest/flow/ai-support/ai-powered-chart.md): Use ChartAIController to let users build and update Highcharts visualizations from the application database using natural language.
- [AI Form Filler](https://vaadin.com/docs/latest/flow/ai-support/ai-powered-form.md): Use FormAIController to let users fill any Vaadin form from natural-language input or attached files.

## <a id="related-components"></a>Related Components

| Component                                                                   | Usage recommendations                                                                                                                                                      |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Message Input](https://vaadin.com/docs/latest/components/message-input.md) | Text input for user messages. Pass to the orchestrator with `withInput()`.                                                                                                 |
| [Message List](https://vaadin.com/docs/latest/components/message-list.md)   | Displays messages. Pass to the orchestrator with `withMessageList()`.                                                                                                      |
| [Upload](https://vaadin.com/docs/latest/components/upload.md)               | File uploads via `UploadManager`. Pass to the orchestrator with `withFileReceiver()`.                                                                                      |
| [Grid](https://vaadin.com/docs/latest/components/grid.md)                   | Populated from the application database via natural-language requests. See [AI-Powered Grid](https://vaadin.com/docs/latest/flow/ai-support/ai-powered-grid.md).           |
| [Charts](https://vaadin.com/docs/latest/components/charts.md)               | Built and updated from the application database via natural-language requests. See [AI-Powered Chart](https://vaadin.com/docs/latest/flow/ai-support/ai-powered-chart.md). |
| [Form Layout](https://vaadin.com/docs/latest/components/form-layout.md)     | Fields can be filled in from natural-language input or attached files. See [AI Form Filler](https://vaadin.com/docs/latest/flow/ai-support/ai-powered-form.md).            |