AI Agents in Java: Architecting Intelligent Health Data Systems

Executive Summary

Modern health data analytics increasingly leverage AI agent software components that process information and make decisions, often using large language models (LLMs) or machine learning models. In Java, you can build agentic systems using libraries like DJL (Deep Java Library), Spring AI, or by integrating LLM APIs. This document includes Maven setup, minimal Spring Boot code (controllers and services), a simple agent example, diagrams, and a comparison of different agent approaches.

Flowchart

Maven Dependencies

Define the necessary dependencies in pom.xml (Spring Web, Validation, DJL, OpenAI SDK, etc.):

<dependencies>

  <!-- Spring Boot Web for API -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>

  <!-- Validation (optional) -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
  </dependency>

  <!-- OpenAI Java SDK (LLM API) -->
  <dependency>
    <groupId>com.openai</groupId>
    <artifactId>openai-java</artifactId>
    <version>4.0.0</version>
  </dependency>

  <!-- DJL for local ML inference -->
  <dependency>
    <groupId>ai.djl</groupId>
    <artifactId>api</artifactId>
    <version>0.36.0</version>
  </dependency>

  <dependency>
    <groupId>ai.djl.mxnet</groupId>
    <artifactId>mxnet-engine</artifactId>
    <version>0.36.0</version>
  </dependency>

  <!-- (Optional) Spring AI -->
  <dependency>
    <groupId>org.springframework.experimental</groupId>
    <artifactId>spring-boot-starter-ai</artifactId>
    <version>0.0.1</version>
  </dependency>

</dependencies>

This setup assumes you will use the OpenAI Java SDK and DJL. Replace the spring-boot-starter-ai version with the latest as needed.

1. Domain Model & Configuration

Define simple data classes for health analysis requests and responses in com.example.health:

package com.example.health;

public record VitalSigns(
    double temperature,
    double bloodPressure,
    int heartRate
) {}

This example record holds patient vitals. You can also add a Spring @Configuration if needed, for example, to configure the DJL engine:

package com.example.config;

import org.springframework.context.annotation.Configuration;
import ai.djl.Engine;

@Configuration
public class DjLConfig {

    public DjLConfig() {
        Engine.getEngine("MXNet");
    }
}

No special configuration is required for OpenAI; it reads API keys from the OPENAI_API_KEY environment variable.

2. Service Layer / Agent Component

Implement a service that acts as your “agent.” It can use a local DJL model or call an external LLM API:

package com.example.agent;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
import org.springframework.stereotype.Service;

@Service
public class HealthAgent {

    private final OpenAIClient openAiClient;

    public HealthAgent() {
        this.openAiClient = OpenAIOkHttpClient.fromEnv();
    }

    public String analyzeVitals(String patientId, VitalSigns vitals) {
        String prompt = String.format(
            "Patient %s has temperature %.1f°C, blood pressure %.0f/%d, heart rate %d. Suggest the next diagnostic step.",
            patientId, vitals.temperature(), vitals.bloodPressure(), vitals.bloodPressure(), vitals.heartRate()
        );

        ResponseCreateParams params = ResponseCreateParams.builder()
                .model("health")
                .input(prompt)
                .build();

        Response response = openAiClient.responses().create(params);
        return response.outputText();
    }
}

This HealthAgent service builds a prompt from VitalSigns and uses the OpenAI Java SDK to call the LLM.

3. REST Controller

Expose an HTTP API to trigger the agent:

package com.example.api;

import com.example.agent.HealthAgent;
import com.example.health.VitalSigns;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/health")
public class HealthController {

    private final HealthAgent agent;

    public HealthController(HealthAgent agent) {
        this.agent = agent;
    }

    @PostMapping("/analyze")
    public ResponseEntity<String> analyze(
            @RequestParam String patientId,
            @RequestBody VitalSigns vitals) {

        String result = agent.analyzeVitals(patientId, vitals);
        return ResponseEntity.ok(result);
    }
}

This controller maps POST /api/health/analyze?patientId=XYZ with a JSON body containing VitalSigns. It delegates to the HealthAgent and returns the response.

4. Agent Patterns and Architecture

AI “agents” can follow different patterns. Spring AI documentation distinguishes workflows from fully agentic systems that act autonomously. In healthcare, predictable workflows are often preferred for safety, although LLM-based agents can be dynamic.

Common agent patterns include:

• Chaining: Multi-step reasoning
• Parallelization: Running tasks in parallel and combining results
• Routing: Directing inputs to specialized prompts or tools
• Looping: Iterating until a goal is achieved

Spring AI provides abstractions to implement these patterns. For example, a chain workflow may sequentially call ChatClient.prompt(...).call() while passing outputs between steps.

The example above is a single-step LLM call, but the architecture can be expanded:

Clients → Spring Boot API → Agent (Spring AI or custom logic) → LLM/model → API response

5. Table: Agent Approaches

6. Implementation Timeline

• 2026-02-01: Project kickoff (set up Spring Boot)
• 2026-02-03: Define domain models (VitalSigns, etc.)
• 2026-02-05: Configure dependencies (DJL, OpenAI SDK)
• 2026-02-07: Implement HealthAgent service (LLM call)
• 2026-02-10: Add REST controller and test endpoint
• 2026-02-12: Optional: integrate DJL model (local inference)
• 2026-02-14: Add error handling and validation
• 2026-02-15: Final testing and local deployment

7. Running Locally

Set your API key:
Ensure OPENAI_API_KEY is set as an environment variable.

Build and run (using Maven):

mvn spring-boot:run

By default, the app runs on http://localhost:8080.

Test the API:

curl -X POST "http://localhost:8080/api/health/analyze?patientId=123" \
     -H "Content-Type: application/json" \
     -d '{"temperature": 38.5, "bloodPressure": 130, "heartRate": 95}'

You should see the AI agent’s response as plain text.

8. Assumptions

• Java Version: Java 17 (no license restrictions assumed)
• External Services: OpenAI or other LLM APIs require network access and valid API keys
• Data Privacy: Health data must be handled securely (e.g., encryption, HIPAA compliance)
• Machine Learning: DJL uses MXNet by default; GPU acceleration requires proper setup
• Architecture: Kafka, WebSockets, or databases are omitted for brevity 

Conclusion

This document outlines how to integrate AI agents into a Spring Boot Java application. Key takeaways:

• Project Setup: Use Spring Boot for REST APIs with ML/LLM dependencies
• Agent Logic: Implement services that call LLM APIs or local ML models
• Patterns: Use structured agent patterns for complex workflows
• Trade-offs: Choose between custom logic, local ML, or LLM APIs based on requirements