Interface AiServiceInvocationSummaryEvent

All Superinterfaces:
AiServiceEvent
All Known Implementing Classes:
DefaultAiServiceInvocationSummaryEvent
public interface AiServiceInvocationSummaryEvent extends AiServiceEvent
A composite event summarizing a single AI Service invocation: all the events fired for it.

It is fired once an invocation is over, right after its AiServiceCompletedEvent, AiServiceErrorEvent or AiServiceCancelledEvent, and contains every AiServiceEvent fired for that invocation (i.e. every event sharing its InvocationContext.invocationId()), in the order they were fired, starting with the AiServiceStartedEvent and ending with the AiServiceCompletedEvent, AiServiceErrorEvent or AiServiceCancelledEvent. In between, it also contains one AiServiceInvocationSummaryEvent for each nested invocation (see below), which has its own invocation id.

A few things to keep in mind:

  • Events are collected if an AiServiceInvocationSummaryListener is registered when the invocation starts, or if the events of its parent invocation are being collected.
  • The event is only fired once the invocation fires its AiServiceCompletedEvent, AiServiceErrorEvent or AiServiceCancelledEvent. AI Services always fire exactly one of them; for an AI Service implementation that does not (for example one built by an integration), the collected events are held until then.
  • Events fired for an invocation after it has ended (for example ToolCompensatedEvents fired once a canceled invocation has been rolled back) are not included.
  • An AI Service invoked while another AI Service invocation is in progress (for example from within a tool) is a separate invocation with its own invocation id. If it is linked to the enclosing invocation (its InvocationContext.parentInvocationId() is not null), its summary is added to the enclosing invocation's events when it ends, and is still fired independently to its own listeners. Its own events are only in its summary, not in the enclosing invocation's events. A linked invocation that ends before the enclosing invocation's AiServiceStartedEvent (for example one called by the chat memory provider or the system message provider) or after the enclosing invocation has ended is not included.
  • For an AI Service method returning a TokenStream, the invocation starts when the method is called, but only ends once the stream has been started with TokenStream.start(). Events collected for a TokenStream that is never started are never released, so always start the streams you create. If start() fails because of a configuration error (for example a missing error handler), the invocation ends with an AiServiceErrorEvent; calling start() again once fixed starts a new invocation.
  • Each subscription to the reactive stream returned by an AI Service method, and each call of TokenStream.start(), is a separate invocation with its own invocation id, so it results in its own AiServiceInvocationSummaryEvent, also when several subscriptions run at the same time.

This event is fired by the AiServiceListenerRegistrar itself and cannot be fired directly.