Package com.tnsai.annotations

Annotation Interface EventHandler

@Documented @Retention(RUNTIME) @Target(METHOD) public @interface EventHandler
Marks a method as an event handler for agent events.

Event handlers are automatically registered and invoked when matching events are published through the event system.

Usage


 public class NotificationAgent extends Agent {

     @EventHandler(event = "task.completed")
     public void onTaskCompleted(TaskCompletedEvent event) {
         System.out.println("Task completed: " + event.getTaskId());
     }

     @EventHandler(event = "error.occurred", async = true)
     public void onError(ErrorEvent event) {
         alertService.sendAlert(event.getMessage());
     }

     @EventHandler(event = "user.*", pattern = true)
     public void onUserEvent(UserEvent event) {
         // Handles user.login, user.logout, user.update, etc.
     }
 }

Event Types

TnsAI provides built-in events:

  • agent.started - Agent lifecycle start
  • agent.stopped - Agent lifecycle stop
  • action.started - Action execution start
  • action.completed - Action execution complete
  • action.failed - Action execution failed
  • message.received - Inter-agent message received
  • llm.response - LLM response received

Async Execution

Set async = true for non-blocking event handling. Async handlers run in a separate thread pool.

Author:
TnsAI Team
See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    event
    Event name or pattern to handle.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    async
    Whether to execute handler asynchronously.
    String
    condition
    Filter condition (SpEL expression).
    int
    maxRetries
    Maximum retry attempts on handler failure.
    int
    order
    Execution order when multiple handlers match.
    boolean
    pattern
    Whether event name is a pattern (supports wildcards).
    boolean
    receiveSelf
    Whether handler should receive events from self.
    int
    retryBackoffMs
    Retry backoff in milliseconds.
    int
    timeout
    Timeout for handler execution in milliseconds.

  • Element Details

    • event

      String event
      Event name or pattern to handle.

      Examples:

      • "task.completed" - Exact match
      • "task.*" - Wildcard (requires pattern=true)
      • "agent.lifecycle.*" - Nested wildcard
      Returns:
      event name or pattern

    • pattern

      boolean pattern
      Whether event name is a pattern (supports wildcards).

      If true, * matches any segment.

      Returns:
      true for pattern matching
      Default:
      false

    • async

      boolean async
      Whether to execute handler asynchronously.

      Async handlers don't block the event publisher.

      Returns:
      true for async execution
      Default:
      false

    • order

      int order
      Execution order when multiple handlers match.

      Lower values execute first.

      Returns:
      order value
      Default:
      100

    • receiveSelf

      boolean receiveSelf
      Whether handler should receive events from self.

      If false, events emitted by this agent are ignored.

      Returns:
      true to receive own events
      Default:
      false

    • condition

      String condition
      Filter condition (SpEL expression).

      Only events matching the condition are handled. 

      
 @EventHandler(event = "task.completed", condition = "event.priority == 'HIGH'")
      Returns:
      SpEL condition
      Default:
      ""

    • maxRetries

      int maxRetries
      Maximum retry attempts on handler failure.

      0 means no retries.

      Returns:
      max retries
      Default:
      0

    • retryBackoffMs

      int retryBackoffMs
      Retry backoff in milliseconds.
      Returns:
      backoff delay
      Default:
      1000

    • timeout

      int timeout
      Timeout for handler execution in milliseconds.

      0 means no timeout.

      Returns:
      timeout in ms
      Default:
      0