Module jakarta.ai.agent

Package jakarta.ai.agent

package jakarta.ai.agent
Jakarta Agentic AI - API for building autonomous agents.

This package provides the fundamental APIs for developing agents that can perceive, reason, decide, and act autonomously within a Jakarta EE environment. Agents are CDI-managed beans that encapsulate goal-driven behavior using a structured workflow model with well-defined lifecycle phases.

Core Components

Agent Annotations

Core Interfaces

CDI Integration

Data Models

  • Result - Standardized decision outcome record
  • LLMException - Runtime exception for LLM operation failures

Workflow Execution Model

An agent workflow is flexible and begins with a required trigger, followed by any combination of optional decision and action phases. Workflows support simple linear execution currently, with potential for more complex dynamic conditional branching in future versions.

Workflow Phases

  1. Trigger Phase (required) - Exactly one @Trigger method is invoked when a CDI event matching its parameters is fired. This initiates the workflow. Triggers support two return patterns:
    • void - Performs initialization with side effects only
    • Domain Object - Returns an object available for injection in subsequent phases
  2. Decision Phases (optional) - Zero or more @Decision methods analyze the workflow state and determine whether to proceed. They support three return patterns:
    • Boolean - true to proceed, false to terminate
    • Result - Success flag with optional details
    • Object - Non-null to proceed (object available for injection), null to terminate
  3. Action Phases (optional) - Zero or more @Action methods execute operations as part of the workflow. Actions can execute independently or based on prior decisions. Actions support two return patterns:
    • void - Performs side effects only (e.g., alerts, database updates)
    • Domain Object - Returns an object available for injection in subsequent workflow methods
  4. Outcome Phase (optional) - Zero or one @Outcome method handles finalization, state persistence, and downstream notifications. Must return void.
  5. Exception Handling (optional) - Zero or more @HandleException methods handle exceptions throughout the workflow lifecycle. Handler returns normally to continue workflow (after recovery), or re-throws exception to stop workflow.

Flexible Composition

Decisions and actions can be intermixed in any sequence, allowing patterns such as:

  • Trigger + Action (simple execution without decisions)
  • Trigger + multiple Actions (sequential processing)
  • Trigger + Decision + Action (conditional execution)
  • Trigger + Decision + Action + Decision + Action (complex branching)

Methods execute in declaration order within the source file.

Usage Example


 import jakarta.ai.agent.*;
 import jakarta.enterprise.inject.Produces;
 import jakarta.inject.Inject;

 @Agent(name = "ExampleAgent", description = "An example autonomous agent")
 public class ExampleAgent {

     @Inject
     private LargeLanguageModel llm;

     @Trigger
     public void onEvent(MyEvent event) {
         // Triggered by CDI event
     }

     @Decision
     public boolean shouldProceed(MyEvent event) {
         String analysis = llm.query("Should we process this event?", event);
         return analysis.contains("yes");
     }

     @Action
     public void executeAction(MyEvent event) {
         // Perform the action with side effects
         notifySystem(event);
     }

     @Outcome
     public void recordOutcome(MyEvent event) {
         // Finalize and persist results
     }
 }

CDI Integration

Agents are CDI-managed beans that integrate seamlessly with Jakarta EE:

  • Dependency injection of other CDI beans
  • Custom @WorkflowScoped scope for workflow-level lifecycle
  • CDI event observation
  • Interceptor support for cross-cutting concerns

Large Language Model Integration

The LargeLanguageModel interface provides a minimal, type-converting facade for LLM operations. Implementations can support:

  • Parameterized text prompts with structured context objects
  • String and domain object returns
  • Unwrapping for vendor-specific features

LLM operations may throw:

  • IllegalArgumentException - For null or invalid parameters, or serialization failures on input parameters
  • LLMException - Runtime exception for LLM service failures (communication errors, rate limiting, timeouts, invalid responses) or response deserialization failures

These exceptions can be handled with try-catch blocks or @HandleException methods for workflow-level error handling.

Parameter Injection

Workflow methods automatically receive parameters based on type resolution:

  • Trigger event objects - From the workflow trigger
  • Decision results - Objects returned from @Decision methods
  • Action results - Objects returned from @Action methods
  • LargeLanguageModel - Injected LLM facade
  • Any CDI injectable dependencies - Standard Jakarta EE beans and resources
Since:
1.0
See Also:
  • Class
    Description
    Action
    Marks a method as an action in an agent workflow.
    Agent
    Declares a class as an AI agent.
    Decision
    Marks a method as a decision point in an agent workflow.
    HandleException
    Marks a method as an exception handler within an agent workflow.
    LargeLanguageModel
    Minimal facade for Large Language Model (LLM) operations.
    LLMException
    Runtime exception thrown when a Large Language Model (LLM) operation fails.
    Outcome
    Marks a method as the outcome of an agent workflow.
    Result
    Represents the result of a decision or workflow step in an agent.
    Trigger
    Marks a method as an external trigger that initiates an agent workflow.
    WorkflowScoped
    Defines a workflow-scoped CDI context.
    WorkflowScoped.Literal
    Supports inline instantiation of the WorkflowScoped annotation.