Module jakarta.ai.agent
Package jakarta.ai.agent

Annotation Interface Action

@Target(METHOD) @Retention(RUNTIME) public @interface Action
Marks a method as an action in an agent workflow.

Actions perform operations as part of the agent's workflow execution. Actions can execute independently or based on prior decision outcomes, allowing both simple sequential processing and complex conditional workflows. Actions typically perform the primary work of the agent, such as persisting data, calling external services, or updating system state.

Multiple action methods can be defined in a single agent. Actions and decisions can be intermixed to create sophisticated branching logic.

Execution Order
The execution order of @Action and @Decision methods is determined by the following precedence rules, applied in order:

  1. @Priority on the method — the annotation value is the sort key; lower values execute first.
  2. order() attribute — used as the sort key when @Priority is absent on the method; lower values execute first.
  3. Source declaration order — used when no action or decision method in the agent declares either @Priority or an explicit order. In this case, methods execute in the order they are declared in the source code. Note that Java SE does not guarantee that reflection returns methods in source declaration order. However, all major JVM implementations do so in practice. Portable applications that require a strict, guaranteed execution order must use @Priority or order.
Consistency requirement: if any @Action or @Decision method in an agent declares an explicit order or @Priority, every @Action and @Decision method in that agent must do the same. Mixing explicitly ordered and unordered methods is a deployment error.

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

  • Workflow state domain objects - Any objects from previous workflow phases, particularly decision results or trigger event objects
  • Decision results - Objects returned from @Decision methods (when using the Object or Result return patterns)
  • LargeLanguageModel - LLM instance for analysis or content generation
  • 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 (e.g., @Valid, @NotNull, @NotEmpty). Validation occurs before the action method is invoked. Validation failures raise jakarta.validation.ConstraintViolationException, which can be handled by @HandleException methods.

Return types
Action methods support two return patterns:

  • void - The action performs work with side effects (e.g., sending alerts, updating databases). No data is passed to subsequent phases.
  • Domain objects - The action returns an object (non-void) that will be automatically injected into subsequent life-cycle methods. Use this pattern to pass action results forward in the workflow.

Examples


 // Void return - performs side effects only
 @Action
 public void handleFraud(Fraud fraud, BankTransaction transaction) {
     if (fraud.isSerious()) {
         alertBankSecurity(fraud);
     }
     Customer customer = getCustomer(transaction);
     alertCustomer(fraud, transaction, customer);
 }

 // Domain object return - passes result to outcome phase
 @Action
 public FraudReport processFraudCase(Fraud fraud, BankTransaction transaction) {
     FraudReport report = new FraudReport();
     report.setFraudType(fraud.getType());
     report.setTransaction(transaction);
     report.setTimestamp(System.currentTimeMillis());
     persistReport(report);
     return report;
 }

 // Receives decision result object
 @Action
 public void executeDocumentation(DocumentationAnalysis analysis, PullRequest pr) {
     if (analysis.requiresDocumentation()) {
         generateDocs(analysis, pr);
         createDocumentationPullRequest(analysis);
     }
 }

 // Later phases receive the action result
 @Outcome
 public void recordOutcome(FraudReport report) {
     auditLog("Fraud case processed: " + report.getId());
 }
Since:
1.0
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    int
    order
    The position of this action in the workflow execution sequence.

  • Element Details

    • order

      int order
      The position of this action in the workflow execution sequence. Lower values execute first.

      Ignored when @Priority is also present on the method — @Priority takes precedence.

      Defaults to 0. When all @Action and @Decision methods in an agent use the default value, source declaration order determines execution order. If any method in the agent explicitly sets order or declares @Priority, all other @Action and @Decision methods in that agent must also declare one.

      Returns:
      the sort key for this action; lower values execute first
      Default:
      0