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

Marks a method as an exception handler within an agent workflow.

Exception handler methods provide agent-specific error recovery when exceptions occur during any workflow phase (trigger, decision, action, or outcome). The handler is invoked with the thrown exception, allowing the agent to perform recovery actions, logging, cleanup, or alternative workflows.

Workflow Control:

To continue workflow: Handler completes successfully (returns normally)
To stop workflow: Handler re-throws the exception or throws a new exception

Parameters
Exception handler methods can have the following types of parameters that will be automatically resolved:

Exception parameter (required) - The thrown exception or its supertype. The most specific matching handler is invoked based on exception type.
Workflow state domain objects - Any objects from previous workflow phases, particularly the trigger event or decision/action results
LargeLanguageModel - LLM instance for analysis or diagnostics
Any other CDI injectable dependencies available to the agent - typically in the application scope or managed by the container

Parameters can declare Jakarta Validation constraints; however, constraint violations are typically not appropriate for exception handlers. If validation of exception handler parameters fails, the validation exception is propagated to the container.

Return type
Exception handler methods MUST return void. Handlers are designed for error recovery, logging, and cleanup rather than producing workflow data.

Semantics

Invoked when exceptions occur in any workflow phase
Most specific exception type match is selected (follows Java exception hierarchy)
Workflow continues if handler returns normally (successful recovery)
Workflow stops if handler throws an exception (re-throw or new exception)
If no matching handler exists, exception propagates to container
Handler exceptions propagate to container (no recursive handling)

Examples


 // Recoverable error - returns normally, workflow continues
 @HandleException
 public void handleRecoverable(IOException ex, BankTransaction transaction) {
     logger.warn("I/O error, retrying transaction: " + transaction.getId(), ex);
     retryQueue.add(transaction);
     // Returns normally - workflow continues
 }

 // Fatal error - re-throws, workflow stops
 @HandleException
 public void handleFatal(SecurityException ex, BankAccount account) {
     logger.error("Security violation", ex);
     auditService.logSecurityBreach(account);
     throw ex; // Re-throw - workflow stops, propagates to container
 }

 // Conditional recovery - decides whether to continue or stop
 @HandleException
 public void handleWithFallback(Exception ex) {
     if (isRecoverable(ex)) {
         logger.info("Recovering from error", ex);
         performRecovery(ex);
         // Returns normally - workflow continues
     } else {
         logger.error("Unrecoverable error", ex);
         throw new WorkflowFailureException("Unrecoverable error", ex);
         // Workflow stops
     }
 }

 // Multiple handlers for different exception types
 @HandleException
 public void handleValidationError(ValidationException ex) {
     logger.warn("Validation failed: " + ex.getMessage());
     // Returns normally - workflow continues with validation flag set
 }

 @HandleException
 public void handleGenericError(Exception ex) {
     logger.error("Unexpected error", ex);
     alertService.notifyAdministrators(ex);
     throw ex; // Stop workflow for unexpected errors
 }

 // Handler with LLM for diagnostics
 @HandleException
 public void handleWithDiagnostics(Exception ex, LargeLanguageModel llm) {
     String analysis = llm.query(
         "Analyze this error and suggest recovery",
         ex);
     logger.info("LLM diagnostic: " + analysis);

     if (analysis.contains("recoverable")) {
         // Continue workflow based on LLM analysis
         return;
     }
     throw ex; // Stop if not recoverable
 }

Since:

1.0

See Also:

Annotation Interface HandleException