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

Interface ResponseListener

All Superinterfaces:
Serializable
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface ResponseListener extends Serializable
Listener for LLM response events.

The listener is called when the turn ends — normally when the assistant's stream has completed, whether successfully or with an error, but also when the turn fails before a stream ever opens. It fires at most once per prompt: a prompt rejected by the RequestInterceptor and a postponed prompt abandoned because its UI was detached end without firing it. The same lifecycle moment as AIController.onResponse(Throwable). Use it to persist conversation state (via AIOrchestrator.getHistory()), trigger follow-up actions, or surface errors to the user.

On success the response text may still be empty if the model emitted only tool calls or stopped without producing visible content. Such turns are successful exchanges; check event.getResponse().isEmpty() if the listener should only react to text-bearing responses. Empty responses are not appended to AIOrchestrator.getHistory().

On failure ResponseListener.ResponseEvent.getError() carries the cause (timeout, stream error, any throw between AIController.onRequest() and the start of the stream, or a RequestInterceptor failure — a throw, a fail, or an interception timeout); the response text is either empty or a partial stream that was received before the failure. An interceptor failure fires the listener without a preceding AIController.onRequest(), so an error does not imply that per-turn setup has happened.

The listener is not called when history is restored via Builder.withHistory().

Threading: the listener is called from whichever thread ends the turn. Stream completion and stream errors arrive on a background thread — where blocking I/O (e.g. database writes) is safe — unless the provider runs the turn on the thread that triggered the prompt, in which case the listener runs there too and blocking prolongs the current request. That is the case for a non-streaming provider with background execution disabled, which is the default. Interception timeouts arrive on a blocking-tolerant Reactor thread, synchronous failures on the UI thread, and a postponed prompt completes on the application's own thread. To update Vaadin UI components from this listener, use ui.access().

Since:
25.2

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    ResponseListener.ResponseEvent
    Event fired when a turn ends, on success or failure.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    onResponse(ResponseListener.ResponseEvent event)
    Called when the turn has ended (see the class documentation for the exact moments).

  • Method Details

    • onResponse

      void onResponse(ResponseListener.ResponseEvent event)
      Called when the turn has ended (see the class documentation for the exact moments).
      Parameters:
      event - the response event