Package com.tnsai.annotations

Annotation Interface CompletionSignal

@Documented @Retention(RUNTIME) @Target(METHOD) public @interface CompletionSignal
Marks an action as a completion signal that terminates the agent loop.

When an action marked with this annotation is called, it signals that the current task is complete. The action should throw a TaskCompleteException to terminate the loop.

Problem Solved

In agentic loops, the LLM needs a way to signal that the task is done. This annotation provides a declarative way to define completion actions that integrate with the RefinementLoop from Phase 9.

Usage


 @ActionSpec(type = ActionType.LOCAL)
 @CompletionSignal
 public void markComplete(String summary) {
     throw new TaskCompleteException(summary);
 }

 // Or with automatic exception
 @ActionSpec(type = ActionType.LOCAL)
 @CompletionSignal(autoComplete = true)
 public String done(String result) {
     return result; // Will be wrapped in TaskCompleteException
 }

Integration with RefinementLoop


 RefinementLoop loop = RefinementLoop.builder()
     .completionCriteria(CompletionCriteria.builder()
         .onCompletionSignal()  // Detect @CompletionSignal actions
         .maxIterations(10)
         .build())
     .build();

When to Use

  • Explicit task completion in agentic loops
  • Browser automation "done" signals
  • Multi-step task finalization
  • Workflow termination points
Author:
TnsAI Team
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    autoComplete
    Whether to automatically wrap the return value in TaskCompleteException.
    String
    description
    Description of what this completion signal indicates.
    boolean
    success
    Whether this completion signal indicates success.
    String[]
    tags
    Tags for categorizing completion types.

  • Element Details

    • description

      String description
      Description of what this completion signal indicates.

      Useful for logging and debugging purposes.

      Returns:
      completion description (default: "Task completed")
      Default:
      "Task completed"

    • autoComplete

      boolean autoComplete
      Whether to automatically wrap the return value in TaskCompleteException.

      When true, the action's return value will be automatically wrapped in a TaskCompleteException after execution, without requiring the method to throw the exception explicitly.

      Returns:
      true to auto-wrap return value (default: false)
      Default:
      false

    • success

      boolean success
      Whether this completion signal indicates success.

      Used for metrics and logging. A failed completion might indicate the task couldn't be completed but the loop should still terminate.

      Returns:
      true if completion is successful (default: true)
      Default:
      true

    • tags

      String[] tags
      Tags for categorizing completion types.

      Useful for analytics and filtering completion events.

      Returns:
      array of tags (default: empty)
      Default:
      {}