Jakarta Agentic AI Specification

@Agent
public class MonitoringAgent {

    @Inject
    private LargeLanguageModel llm;

    @Inject
    private EventLogger logger;

    @Trigger
    public void onSystemAlert(Alert alert) {
        // Triggered by an external CDI event
    }

    @Decision
    public boolean shouldEscalate(Alert alert) {
        String analysis = llm.query("Should this alert be escalated?", alert);
        return analysis.toLowerCase().contains("yes");
    }

    @Action
    public void escalateAlert(Alert alert) {
        logger.logEscalation(alert);
    }
}

@Agent
public class DataIntegratedAgent {

    @Inject private EntityManager entityManager;            // Jakarta Persistence
    @Inject private CustomerRepository customerRepo;        // Jakarta Data
    @Inject private Template mongoTemplate;                 // Jakarta NoSQL
    @Inject private ManagedExecutorService executor;        // Jakarta Concurrency

    @Action
    @Transactional                                          // Jakarta Transactions
    public void processCustomerData(
            @Valid @NotNull CustomerId id) {                // Jakarta Validation
        Customer customer = entityManager.find(Customer.class, id);
        List<Order> orders = customerRepo.findOrdersByCustomerId(id);
        mongoTemplate.insert(new AnalyticsEvent(customer, orders));
        executor.submit(() -> generateReport(customer, orders));
    }
}

@Agent
public class ResilientAgent {

    @Trigger
    public void onEvent(Event event) {
        if (event == null) {
            throw new IllegalArgumentException("Event cannot be null");
        }
    }

    @Decision
    public boolean analyze(Event event) {
        return analyzeEvent(event); // may throw IOException
    }

    @HandleException
    public void handleIOException(IOException e, Event event) {
        logger.warn("I/O error, will retry", e);
        scheduleRetry(event);
    }

    @HandleException
    public void handleGenericException(Exception e, Event event) {
        logger.error("Unexpected error", e);
        logFailure(event, e);
    }
}

@Agent
public class TransactionalAgent {

    @Inject
    private EntityManager entityManager;

    @Action
    @Transactional
    public void updateDatabase(Data data) {
        entityManager.persist(data);
    }
}

@Agent
@WorkflowScoped
public class LifecycleAwareAgent {

    private static final Logger logger =
            Logger.getLogger(LifecycleAwareAgent.class.getName());

    @Inject
    private ResourcePool resources;

    @PostConstruct
    public void initialize() {
        logger.info("Agent initialized");
        resources.allocate();
    }

    @PreDestroy
    public void cleanup() {
        logger.info("Agent destroying");
        resources.release();
    }
}

@Agent(description="Detects bank fraud transactions")
public class FraudDetectionAgent {

    @Inject
    private LargeLanguageModel model;

    @Inject
    private EntityManager entityManager;

    @Inject
    private AlertService alertService;

    @Trigger
    public void processTransaction(@Valid BankTransaction transaction) {
        logger.info("Processing transaction: " + transaction.getId());
    }

    @Decision
    public Result checkFraud(BankTransaction transaction) {
        FraudAssessment assessment = model.query(
            """
            Analyze this transaction for fraud:
            Amount: {}
            Merchant: {}
            Location: {}

            Respond with JSON: {"isFraud": true/false, "confidence": 0.0-1.0, "reason": "..."}
            """,
            FraudAssessment.class,
            transaction.getAmount(),
            transaction.getMerchant(),
            transaction.getLocation()
        );

        Fraud details = assessment.isFraud()
            ? new Fraud(assessment.confidence(), assessment.reason())
            : null;
        return new Result(assessment.isFraud(), details);
    }

    @Action
    public void alertBankSecurity(Fraud fraud) {
        if (fraud.isSerious()) {
            alertService.alertBankSecurity(fraud);
        }
    }

    @Action
    public void alertCustomer(Fraud fraud, BankTransaction transaction) {
        Customer customer = getCustomer(transaction);
        alertService.alertCustomer(fraud, transaction, customer);
    }

    @Outcome
    @Transactional
    public void finalizeTransaction(BankTransaction transaction, Fraud fraud) {
        transaction.setStatus(TransactionStatus.SUSPECT);
        entityManager.merge(transaction);
        logger.info("Transaction marked as suspect: " + transaction.getId());
    }

    @HandleException
    @Transactional
    public void handleModelUnavailable(LLMException e, BankTransaction transaction) {
        logger.warn("Fraud model unavailable for transaction: " + transaction.getId(), e);
        // Compensate safely: route to manual review when model calls fail
        transaction.setStatus(TransactionStatus.NEEDS_REVIEW);
        entityManager.merge(transaction);
    }
}

@Agent
@ApplicationScoped
public class DocumentationAgent {

    @Inject
    private LargeLanguageModel llm;

    @Inject
    private GitService gitService;

    @Trigger
    public void onPullRequest(PullRequestEvent prEvent) {
        logger.info("Processing PR #" + prEvent.getNumber());
    }

    @Decision
    public DocumentationPlan shouldGenerateDocs(PullRequestEvent prEvent) {
        PullRequest pr = prEvent.getPullRequest();

        DocumentationPlan plan = llm.query(
            """
            Analyze this pull request and determine if documentation is needed.

            Title: {}
            Description: {}
            Changed Files: {}

            Respond with JSON:
            {"needsDocumentation": true/false, "suggestedFiles": ["file1.md"]}
            """,
            DocumentationPlan.class,
            pr.getTitle(),
            pr.getDescription(),
            String.join(", ", pr.getChangedFiles())
        );

        if (!plan.needsDocumentation()) {
            logger.info("No documentation needed for PR #" + pr.getNumber());
            return null; // Stop workflow
        }

        return plan;
    }

    @Action
    public DocumentationFiles generateDocumentation(
        PullRequestEvent prEvent,
        DocumentationPlan plan
    ) {
        PullRequest pr = prEvent.getPullRequest();
        DocumentationFiles files = new DocumentationFiles();

        for (String filename : plan.getSuggestedFiles()) {
            String content = llm.query(
                "Generate documentation for: {}. Diff: {}",
                filename,
                pr.getDiff()
            );
            files.addFile(filename, content);
        }

        return files;
    }

    @Outcome
    public void createDocumentationPR(
        PullRequestEvent originalPr,
        DocumentationFiles files
    ) {
        String branchName = "docs/pr-" + originalPr.getNumber();
        gitService.createBranch(branchName);
        gitService.commitFiles(branchName, files);

        PullRequest docPr = gitService.createPullRequest(
            branchName,
            "main",
            "Documentation for PR #" + originalPr.getNumber()
        );

        logger.info("Created documentation PR #" + docPr.getNumber());
    }

    @HandleException
    public void handleGenerationFailure(LLMException e, PullRequestEvent prEvent) {
        logger.warn("Documentation generation unavailable for PR #" +
            prEvent.getNumber(), e);

        gitService.addComment(
            prEvent.getNumber(),
            "Automatic documentation is temporarily unavailable. " +
            "Please update docs manually for this PR."
        );
    }
}

@Agent
public class CustomerSupportAgent {

    @Inject
    private LargeLanguageModel llm;

    @Inject
    private KnowledgeBaseService knowledgeBase;

    @Inject
    private TicketService ticketService;

    @Inject
    private CustomerService customerService;

    @Inject
    private MessagingService messagingService;

    private Customer customer;

    @Trigger
    public void onCustomerMessage(CustomerMessage message) {
        customer = customerService.getCustomer(message.getCustomerId());
    }

    @Action
    public SupportResponse generateResponse(CustomerMessage message) {
        List<KnowledgeArticle> articles = knowledgeBase.search(message.getText(), 5);

        String llmResponse = llm.query(
            """
            You are a helpful customer support agent.

            Customer: {}
            Relevant Knowledge Base Articles:
            {}

            Customer's Latest Message: {}

            Provide a helpful response. Respond with JSON:
            {"response": "...", "canResolve": true/false, "needsEscalation": true/false}
            """,
            customer.getName(),
            articles.stream().map(a -> a.getSummary()).collect(Collectors.joining("\n")),
            message.getText()
        );
        return parseResponse(llmResponse);
    }

    @Action
    public void sendResponse(SupportResponse response) {
        messagingService.sendToCustomer(customer.getId(), response.getResponse());
    }

    @Outcome
    public void finalizeInteraction(SupportResponse response) {
        if (response.needsEscalation()) {
            ticketService.escalate(customer.getId(), "Agent unable to resolve");
            messagingService.sendToCustomer(
                customer.getId(),
                "I've escalated your issue to a specialist."
            );
        }
    }

    @HandleException
    public void handleModelFailure(LLMException e, CustomerMessage message) {
        logger.warn("Support response generation unavailable", e);
        ticketService.escalate(customer.getId(), "Automated response unavailable");
    }
}

@Agent
public class OnboardingAgent {

    @Inject
    private EmailService emailService;

    // Constraint violations short-circuit the workflow and are recovered by
    // @HandleException below.
    @Trigger
    public void onInvitation(@Valid @NotNull UserInvitation invitation) {
        logger.info("Processing invitation for: " + invitation.getEmail());
    }

    @Decision
    public boolean isEmailActive(UserInvitation invitation) {
        // Format was validated by @Email on UserInvitation; here we confirm
        // the address is actually reachable.
        return emailService.isActiveEmail(invitation.getEmail());
    }

    @Action
    public void sendWelcomeEmail(UserInvitation invitation) {
        User invitee = invitation.getInvitee();
        emailService.send(
            invitation.getEmail(),
            "Welcome " + invitee.getFirstName() + "!"
        );
    }

    @Outcome
    public void markAccepted(UserInvitation invitation) {
        invitation.setStatus(InvitationStatus.ACCEPTED);
    }

    @HandleException
    public void onInvalidInvitation(ConstraintViolationException e,
                                    UserInvitation invitation) {
        for (var v : e.getConstraintViolations()) {
            logger.warn("Invalid: " + v.getPropertyPath() + " - " + v.getMessage());
        }
        invitation.setStatus(InvitationStatus.INVALID);
    }

    // Compensating recovery when the mail service cannot deliver.
    @HandleException
    public void onDeliveryFailure(EmailDeliveryException e,
                                  UserInvitation invitation) {
        logger.error("Unable to deliver welcome email", e);
        invitation.setStatus(InvitationStatus.DELIVERY_FAILED);
    }
}