Package com.vaadin.flow.component.ai.form

Class FormAIController

java.lang.Object
com.vaadin.flow.component.ai.form.FormAIController
All Implemented Interfaces:
AIController
public class FormAIController extends Object implements AIController
Populates a layout's fields with values an LLM extracts from a user prompt or attached files. Attach it to an AIOrchestrator via withController(...).

The controller accepts any HasComponents container. It discovers fields by walking the container's component tree and collecting every component that implements HasValue. The walk recurses into nested HasComponents children so layouts containing layouts are handled.

Serialization: the controller is not serialized with the orchestrator. After deserialization, create a new controller against the same form and call orchestrator.reconnect(provider).withController(controller).apply().

Author:
Vaadin Ltd

  • Constructor Details

    • FormAIController

      public FormAIController(T form)
      Creates a new form AI controller for the given container. Fields are discovered by walking the container's component tree each time the controller is asked for tools, so fields added or removed between turns are picked up automatically.
      Type Parameters:
      T - the container type
      Parameters:
      form - the container whose fields the LLM may populate, not null

  • Method Details

    • describe

      public FormAIController describe(HasValue<?,?> field, String description)
      Adds a free-form description that the LLM sees alongside the field when deciding what to fill in. Use it to add business semantics that are not implied by the field's label, helper text, or component type (for example clarifying that a numeric field expects a percentage rather than an absolute amount). Later calls for the same field overwrite earlier ones.
      Parameters:
      field - the field to describe, not null
      description - the description text, not null
      Returns:
      this controller, for chaining

    • allowedValues

      public <T> FormAIController allowedValues(HasValue<?,T> field, List<? extends T> values)
      Restricts the field's accepted values to the given list. The LLM is told to pick one of these and the controller rejects anything else. Later calls for the same field overwrite earlier ones.
      Type Parameters:
      T - the field's value type
      Parameters:
      field - the field to constrain, not null
      values - the allowed values, not null; a defensive copy is taken
      Returns:
      this controller, for chaining

    • ignore

      public FormAIController ignore(HasValue<?,?> field)
      Hides the given field from the LLM. The field is excluded from the tool surface and is not locked during a fill. Use this for fields the AI must not read or write (password fields, internal IDs, PII).
      Parameters:
      field - the field to hide, not null
      Returns:
      this controller, for chaining

    • getTools

      public List<LLMProvider.ToolSpec> getTools()
      Description copied from interface: AIController
      Returns the tools this controller exposes to the LLM.
      Specified by:
      getTools in interface AIController
      Returns:
      list of tools, or empty list if controller provides no tools

    • onRequestStart

      public void onRequestStart()
      Description copied from interface: AIController
      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, AIController.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.

      Specified by:
      onRequestStart in interface AIController

    • onResponseComplete

      public void onResponseComplete()
      Description copied from interface: AIController
      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 AIController.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.

      Specified by:
      onResponseComplete in interface AIController