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

Interface AIController

All Known Implementing Classes:
ChartAIController, FormAIController, GridAIController
public interface AIController
Contributes tools and lifecycle hooks to an AIOrchestrator — domain-specific behaviour like populating a grid, building a chart, or filling a form from natural-language requests.

Controllers are not serialized with the orchestrator. After deserialization, restore controllers via reconnect(provider).withController(controller).apply().

Since:
25.2
Author:
Vaadin Ltd

  • Method Summary

    Modifier and Type
    Method
    Description
    List<LLMProvider.ToolSpec>
    getTools()
    Returns the tools this controller exposes to the LLM.
    default void
    onRequest()
    Called synchronously on the UI thread just before the LLM stream opens.
    default void
    onResponse(Throwable error)
    Called when the turn ends: normally when the LLM stream has completed, successfully or with an error, but also when the turn fails before a stream ever opens.

  • Method Details

    • getTools

      List<LLMProvider.ToolSpec> getTools()
      Returns the tools this controller exposes to the LLM.
      Returns:
      list of tools, or empty list if controller provides no tools

    • onRequest

      default void onRequest()
      Called synchronously on the UI thread just before the LLM stream opens. By the time this method fires, the user message and an empty assistant placeholder are already in the message list; the turn is committed to the conversation history and the RequestListener only after this method returns successfully. Implementations can prepare for the turn — locking UI surfaces, snapshotting state the tool definitions depend on, and so on. Since tools may execute on a background thread, this is the moment to capture any state that depends on Vaadin thread locals such as UI.getCurrent() or VaadinSession.getCurrent().

      The default does nothing. Throwing from this method aborts the turn before the commit step: the conversation history is unchanged, the request listener is not notified, the LLM stream is not opened, the assistant placeholder is updated to a generic error message, onResponse(Throwable) fires with the thrown exception so per-turn state captured before the throw can still be released, and the exception propagates back to the caller of the prompt entry point.

    • onResponse

      default void onResponse(Throwable error)
      Called when the turn ends: normally when the LLM stream has completed, successfully or with an error, but also when the turn fails before a stream ever opens. The call runs through ui.access(), so the session lock is held and Vaadin thread locals are bound — though not necessarily on a request thread.

      Fires at most once per prompt. A prompt rejected by the RequestInterceptor ends without firing it, as does a postponed prompt abandoned because its UI was detached. A turn whose UI is detached when it ends also skips the hook, which requires ui.access().

      On success error is null; use the call to commit staged state or run deferred UI updates. On failure error carries the cause (stream error, timeout, or any throw on the prompt path before the stream opens); release per-turn state captured in onRequest (locks, pending writes, snapshots) and discard the staged work. Note that a failure before onRequest() — for example a throwing RequestInterceptor — also fires this method, so it can run without a preceding onRequest call.

      The default does nothing. Exceptions thrown from the hook are caught and logged; Errors propagate.

      Parameters:
      error - the cause of failure, or null on success