@Target(METHOD) @Retention(RUNTIME) public @interface Trigger

Marks a method as an external trigger that initiates an agent workflow.

Trigger methods define the entry point for agent workflows and are invoked when triggering events occur. Currently, triggers are invoked by CDI events. A trigger method may optionally use the @Observes annotation to explicitly handle the triggering event. The triggering event is automatically added to the workflow context for access in subsequent phases.

Scope Restrictions
CDI event observation capabilities depend on the agent's scope:

@WorkflowScoped agents: Can ONLY use @Trigger methods to handle CDI events. General CDI observers (methods with @Observes but without @Trigger) are not supported.
@ApplicationScoped agents: Can use both @Trigger methods AND general CDI observer methods.

While triggers are currently limited to CDI events, future versions may support other event sources, such as Jakarta Messaging messages, manual/programmatic workflow invocation, or REST POST requests.

Currently, there MUST be only one @Trigger method per agent class. This constraint will be relaxed in future versions to support multiple entry points.

Parameters
Trigger methods can have the following types of parameters:

The triggering event (CDI event) - Optionally annotated with @Observes to explicitly declare CDI event observation
LargeLanguageModel - LLM instance for trigger analysis
Any other CDI injectable dependencies available to the agent

Parameters can declare Jakarta Validation constraints (e.g., @Valid, @NotNull, @Email, @Size). Validation occurs before the trigger method is invoked. Validation failures raise jakarta.validation.ConstraintViolationException, which can be handled by @HandleException methods.

Return types
Trigger methods support two return patterns:

void - The trigger handles initialization with side effects only. No data is passed to subsequent phases.
Domain objects - The trigger returns an object (non-void) that will be automatically injected into subsequent workflow methods. Use this pattern to pass trigger analysis or transformation forward in the workflow.

Semantics

Invoked when a CDI event matching the trigger parameter is fired
First phase of workflow execution - creates a new workflow context

Examples


 // Void return - initialization with side effects
 @Trigger
 public void onTransaction(BankTransaction event) {
     logger.info("Workflow triggered for transaction: " + event.getId());
     // Initialization logic only
 }

 // Domain object return - passes analysis to next phases
 @Trigger
 public EventAnalysis analyzeEvent(MyEvent event) {
     EventAnalysis analysis = new EventAnalysis();
     analysis.setSource(event.getSource());
     analysis.setPriority(determinePriority(event));
     return analysis;
 }

 // Trigger with LLM analysis
 @Trigger
 public TriggerResult analyzeTrigger(MyEvent event, LargeLanguageModel llm) {
     String analysis = llm.query("Classify this event", event);
     TriggerResult result = new TriggerResult();
     result.setClassification(analysis);
     result.setEventData(event);
     return result;
 }

Since:

1.0

See Also:

Annotation Interface Trigger