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

Annotation Interface Decision

@Target(METHOD) @Retention(RUNTIME) public @interface Decision
Marks a method as a decision point in an agent workflow.

Decision methods are optional workflow phases that determine whether and how the workflow should proceed. Multiple decision methods can be defined and can be intermixed with actions to create conditional branching logic.

Execution Order
The execution order of @Decision and @Action 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 @Decision or @Action method in an agent declares an explicit order or @Priority, every @Decision and @Action method in that agent must do the same. Mixing explicitly ordered and unordered methods is a deployment error.

Decision methods typically use a LargeLanguageModel to analyze the workflow state and make intelligent decisions.

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

  • Workflow state domain objects - Any objects used by prior phases in the workflow, particularly the triggering event object
  • LargeLanguageModel - LLM instance
  • 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, @Email). Validation occurs before the decision method is invoked. Validation failures raise jakarta.validation.ConstraintViolationException, which can be handled by @HandleException methods.

Return types
Decision methods support multiple return patterns:

  • Boolean: true means proceed with the workflow, false means stop the workflow
  • Result: A Result record with success flag and optional details to control workflow and pass data to subsequent phases
  • Object: A non-null object means proceed (and the object is available for injection into subsequent phases), null means stop the workflow

Examples


 // Boolean return
 @Decision
 public boolean shouldGenerateDocs(PullRequest pr) {
     String response = llm.query(
         "Does this PR require documentation updates?",
         pr);
     return response.contains("yes");
 }

 // Result return - provides structured outcome
 @Decision
 public Result checkFraud(BankTransaction transaction) {
     String output = llm.query(
         "Is this a fraudulent transaction?", transaction);
     boolean fraud = isFraud(output);
     Fraud details = fraud ? getFraudDetails(output) : null;
     return new Result(fraud, details);
 }

 // Object return - provides data for next phases
 @Decision
 public DocumentationPlan planDocumentation(PullRequest pr) {
     String analysis = llm.query(
         "Analyze what documentation is needed for this pull request",
         pr);

     if (analysis.contains("no documentation needed")) {
         return null;  // Stop workflow
     }

     return new DocumentationPlan(analysis);  // Proceed with this plan
 }

 // Later phases can receive the decision result
 @Action
 public void generateDocs(DocumentationPlan plan) {
     // Use the plan from the decision phase
     createDocumentation(plan.getFiles(), plan.getContent());
 }
Since:
1.0
See Also:

  • Optional Element Summary

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

  • Element Details

    • order

      int order
      The position of this decision 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 @Decision and @Action 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 @Decision and @Action methods in that agent must also declare one.

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