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().

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 on the UI thread under the session lock when the LLM stream has completed — either successfully or with an error.

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

      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 on the UI thread under the session lock when the LLM stream has completed — either successfully or with an error. Every turn fires this exactly once.

      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 between onRequest() and the start of the stream); release per-turn state captured in onRequest (locks, pending writes, snapshots) and discard the staged work.

      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