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
    onRequestStart()
    Called synchronously on the UI thread just before the LLM stream opens.
    void
    onResponseComplete()
    Called on the UI thread under the session lock when the LLM stream completes successfully — after all tool calls for the turn have run and the LLM has produced its final response.
    default void
    onResponseFailed(Throwable error)
    Called on the UI thread under the session lock when an LLM turn fails — stream error, timeout, or any throw between onRequestStart() and the start of the stream.

  • 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

    • onRequestStart

      default void onRequestStart()
      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 attachment-submit listener 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 attachment-submit listener is not notified, the LLM stream is not opened, the assistant placeholder is updated to a generic error message, onResponseFailed(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.

    • onResponseComplete

      void onResponseComplete()
      Called on the UI thread under the session lock when the LLM stream completes successfully — after all tool calls for the turn have run and the LLM has produced its final response. Use it for deferred UI updates or to commit staged state.

      Mutually exclusive with onResponseFailed(Throwable): every turn fires exactly one of the two. Exceptions thrown from the hook are caught and the user sees a generic error message; Errors propagate.

    • onResponseFailed

      default void onResponseFailed(Throwable error)
      Called on the UI thread under the session lock when an LLM turn fails — stream error, timeout, or any throw between onRequestStart() and the start of the stream. Implementations should release per-turn state captured in onRequestStart (locks, pending writes, snapshots).

      Mutually exclusive with onResponseComplete(): every turn fires exactly one of the two. The default does nothing. Exceptions thrown from the hook are caught and logged; Errors propagate.

      Parameters:
      error - the cause of the failure (Exception or Error), never null