Spring AI Agentic Patterns: Agent Skills for Clinical Decision Support

New case: 58-year-old male, acute chest pain radiating
to the left arm, diaphoresis, elevated troponin.
Assess urgency.

## Urgency Levels
- **CRITICAL** — life-threatening; immediate attention required
- **HIGH** — urgent; attention required within hours

## Output
Return structured JSON with urgencyLevel, rationale, redFlags, recommendedAction.

{
  "urgencyLevel": "CRITICAL",
  "rationale": "Classic ACS presentation — immediate cardiology consult required",
  "redFlags": ["chest pain", "radiation to arm", "diaphoresis", "elevated troponin"],
  "recommendedAction": "Emergency cardiology consult"
}

// medicalcase/domain/MedicalCase.java
public record MedicalCase(
    String id,                          // CHAR(24) hex ID
    Integer patientAge,                 // anonymised
    String chiefComplaint,
    String symptoms,
    String currentDiagnosis,
    List<String> icd10Codes,            // ICD-10 classification
    List<String> snomedCodes,           // SNOMED-CT codes
    UrgencyLevel urgencyLevel,          // CRITICAL / HIGH / MEDIUM / LOW
    String requiredSpecialty,
    CaseType caseType,                  // INPATIENT / SECOND_OPINION / CONSULT_REQUEST
    String additionalNotes,
    String abstractText,                // embedding source
    BigDecimal locationLatitude,
    BigDecimal locationLongitude
) {}

// doctor/domain/Doctor.java
public record Doctor(
    String id,
    String name,
    List<String> specialtyIds,          // array-ref, no FK
    List<String> icd10CodeRanges,       // competency breadth
    Boolean telehealthCapable,
    String availabilityStatus,
    BigDecimal locationLatitude,
    BigDecimal locationLongitude
) {}

// clinicalexperience/domain/ClinicalExperience.java
public record ClinicalExperience(
    String id,
    String doctorId,
    String caseId,
    String outcome,          // RESOLVED, IMPROVED, REFERRED, ...
    Integer complexityLevel,
    String facilityId,
    Instant recordedAt
) {}

src/main/resources/skills/
├── case-analyzer/       SKILL.md
├── clinical-advisor/    SKILL.md
├── clinical-guideline/  SKILL.md
├── doctor-matcher/      SKILL.md
├── evidence-retriever/  SKILL.md
├── network-analyzer/    SKILL.md
├── recommendation-engine/ SKILL.md
├── routing-planner/     SKILL.md
└── triage/              SKILL.md

---
name: doctor-matcher
description: Match doctors to medical cases using multiple signals
             including vector similarity, graph relationships,
             and historical performance
---

# Doctor Matcher

## When to Use This Skill
- User needs to find specialists for a medical case
- You need to score and rank doctor-case matches
- You need to prioritize doctors based on historical performance

## Available Tools

### querycandidatedoctors
Finds candidate doctors based on case requirements and filters.

Parameters:
- `caseId` — the medical case ID (required)
- `specialty` — required medical specialty (optional)
- `requireTelehealth` — filter to telehealth-capable doctors (optional)
- `maxResults` — maximum number of results, default 10

Returns a list of candidate doctors matching the criteria.

### matchdoctorstocase
Runs the full three-signal match-and-score pipeline for a case.

Parameters:
- `caseId` — the medical case ID
- `maxResults` — default 10
- `minScore` — score threshold (optional)
- `preferredSpecialties` — preferred specialty list (optional)
- `requireTelehealth` — boolean (optional)

Returns doctor matches sorted by score (1 = best match),
with per-signal breakdown and rationale.

## Output Format
For every match provide:
- **Doctor** — name, specialty, certifications, availability
- **Score** — overall 0–100 with component breakdown (vector / graph / history)
- **Rank** — position in results (1 = best match)
- **Rationale** — why this doctor was selected

## Workflow
1. Analyse the case — identify required specialty, urgency, complexity
2. Call `querycandidatedoctors` to get the filtered candidate pool
3. Call `matchdoctorstocase` to score and rank the pool
4. Apply thresholds or preference filters as needed
5. Return ranked results with full rationale

## Medical Disclaimer
All matches are for research and educational purposes only.
Results must be reviewed by qualified medical professionals
before any clinical decision is made.

---
name: triage
description: Assess urgency level for new medical cases. Use when a
  new case enters the system to classify as CRITICAL, HIGH, MEDIUM,
  or LOW priority tier for queue routing.
---

# Triage

## Urgency Levels
- **CRITICAL** — life-threatening; immediate attention required (chest pain, stroke, severe dyspnea)
- **HIGH** — urgent; attention required within hours
- **MEDIUM** — important; attention required within days
- **LOW** — routine; attention within weeks

{
  "urgencyLevel": "CRITICAL",
  "rationale": "Acute chest pain with diaphoresis — ACS must be excluded immediately",
  "redFlags": ["chest pain", "diaphoresis", "elevated troponin"],
  "recommendedAction": "Emergency cardiology consult"
}

// llm/agent/ContextBuilderAgent.java
@Slf4j
@Component
@Profile("event-driven")
@RequiredArgsConstructor
public class ContextBuilderAgent {

    private final ApplicationEventPublisher eventPublisher;
    private final CaseContextBundleService   caseContextBundleService;
    private final PipelineMetricsService     pipelineMetrics;
    private final PipelineProgressCollector  pipelineProgressCollector;

    @EventListener
    public void onPlanReady(PlanReadyEvent event) {
        long start = System.currentTimeMillis();
        log.info("ContextBuilderAgent: plan ready session={} steps={}",
            event.sessionId(), event.plan().steps().size());

        pipelineProgressCollector.addStage(event.sessionId(), CONTEXT_BUILD, "ContextBuilder");

        String          caseId  = findCaseId(event.plan());
        CaseContextIntent intent = resolveIntent(event.plan());

        CaseContextBundle bundle = caseContextBundleService.build(caseId, intent);

        pipelineMetrics.recordContextBuild(event.sessionId(),
            System.currentTimeMillis() - start);

        eventPublisher.publishEvent(
            new ContextReadyEvent(event.sessionId(), bundle, Instant.now()));
    }
}

// retrieval/service/impl/DoctorMatchServiceImpl.java
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class DoctorMatchServiceImpl implements DoctorMatchService {

    private final MedicalCaseRepository         medicalCaseRepository;
    private final SemanticGraphRetrievalService  semanticGraphRetrievalService;
    private final RerankingService               rerankingService;

    @Override
    public List<DoctorMatch> matchDoctorsForCase(
            String caseId, MatchOptions options) {

        String normalizedId = caseId.trim().toLowerCase();

        MedicalCase medicalCase = medicalCaseRepository
            .findById(normalizedId)
            .orElseThrow(() -> new IllegalArgumentException(
                "Medical case not found: " + caseId));

        // Guard: reject cases that contain only ObjectId placeholders
        if (hasInsufficientMedicalData(medicalCase)) {
            log.warn("Case {} has insufficient clinical data for matching", caseId);
            return List.of();
        }

        List<Doctor> candidates = findCandidateDoctors(medicalCase, options);

        List<DoctorMatch> unsorted = candidates.stream()
            .filter(d -> !options.excludedDoctorIds().contains(d.id()))
            .map(doctor -> {
                ScoreResult score =
                    semanticGraphRetrievalService.score(medicalCase, doctor);
                return new DoctorMatch(
                    doctor,
                    score.overallScore(),
                    0,           // rank assigned after sort
                    score.rationale());
            })
            .filter(m -> options.minScore() == null
                         || m.matchScore() >= options.minScore())
            .collect(toList());

        List<DoctorMatch> sorted = unsorted.stream()
            .sorted(comparingDouble(DoctorMatch::matchScore).reversed())
            .collect(toList());

        // Optional semantic re-ranking (disabled by default via feature flag)
        return rerankingService.rerank(normalizedId, sorted, options.maxResults());
    }

    /**
     * A case has insufficient data if all three clinical fields are blank
     * or contain only 24-character hex ObjectId strings.
     */
    private boolean hasInsufficientMedicalData(MedicalCase c) {
        return !isRealMedicalTerm(c.chiefComplaint())
            && !isRealMedicalTerm(c.currentDiagnosis())
            && (c.icd10Codes() == null
                || c.icd10Codes().stream().noneMatch(this::isRealMedicalTerm));
    }

    private boolean isRealMedicalTerm(String value) {
        if (value == null || value.isBlank()) return false;
        // Reject bare ObjectId hex strings (24 hex chars)
        if (value.trim().matches("[0-9a-fA-F]{24}")) return false;
        return value.trim().chars().anyMatch(Character::isLetter);
    }
}

// llm/advisor/LlmUsageCaptureAdvisor.java
public class LlmUsageCaptureAdvisor implements CallAdvisor, StreamAdvisor {

    private final LlmUsageTelemetryService telemetryService;

    @Override
    public String getName() { return "llmUsageCaptureAdvisor"; }

    @Override
    public int getOrder() { return Ordered.LOWEST_PRECEDENCE; }

    // --- Blocking call ---
    @Override
    public ChatClientResponse adviseCall(
            ChatClientRequest request, CallAdvisorChain chain) {
        long start = System.nanoTime();
        ChatClientResponse response = chain.nextCall(request);
        record(request, response, start);
        return response;
    }

    // --- Streaming call ---
    @Override
    public Flux<ChatClientResponse> adviseStream(
            ChatClientRequest request, StreamAdvisorChain chain) {
        long start = System.nanoTime();
        AtomicReference<ChatClientResponse> last = new AtomicReference<>();
        return chain.nextStream(request)
            .doOnNext(last::set)
            .doOnComplete(() -> record(request, last.get(), start));
    }

    private void record(
            ChatClientRequest request,
            ChatClientResponse response,
            long startNanos) {
        if (response == null) return;
        long latencyMs = Math.max(0L, (System.nanoTime() - startNanos) / 1_000_000L);
        LlmCallSnapshot snapshot = LlmCallSnapshot.fromProvider(
            response, request,
            LlmUsageContextHolder.getOrDefault(), latencyMs);
        telemetryService.record(snapshot);
    }
}

// Compact after 15 turns; hard limit 30 events; JDBC-persisted
SessionMemoryAdvisor memoryAdvisor = new SessionMemoryAdvisor(
    jdbcSessionStore,
    new SlidingWindowCompactionStrategy(15, 30));

~/.medexpertmatch/auto-memory/
├── doctor-prefs-abc123.md     # "Dr. Smith prefers cardiology referrals via telehealth"
├── case-patterns-2026-06.md   # recurring chief-complaint patterns this month
└── session-notes-xyz.md       # cross-session continuity notes

// llm/package-info.java
@org.springframework.modulith.ApplicationModule(
    allowedDependencies = {
        "core",
        "doctor",
        "medicalcase",
        "clinicalexperience",
        "medicalcoding",
        "facility",
        "graph",
        "embedding",
        "retrieval",
        "caseanalysis",
        "evidence"
    }
)
package com.berdachuk.medexpertmatch.llm;

// core/config/PromptTemplateConfig.java
@Configuration
public class PromptTemplateConfig {

    @Bean
    public PromptTemplate caseAnalysisPrompt(ResourceLoader resourceLoader) {
        return PromptTemplate.builder()
            .renderer(StTemplateRenderer.builder().build())
            .resource(resourceLoader.getResource(
                "classpath:prompts/case-analysis.st"))
            .build();
    }

    @Bean
    public PromptTemplate doctorMatchRationalePrompt(ResourceLoader resourceLoader) {
        return PromptTemplate.builder()
            .renderer(StTemplateRenderer.builder().build())
            .resource(resourceLoader.getResource(
                "classpath:prompts/doctor-match-rationale.st"))
            .build();
    }
}

<!-- pom.xml -->
<dependency>
    <groupId>org.spring-ai-community</groupId>
    <artifactId>spring-ai-agent-utils</artifactId>
    <version>0.9.0</version>
</dependency>

// llm/config/MedicalAgentConfiguration.java
@Configuration
@RequiredArgsConstructor
public class MedicalAgentConfiguration {

    private final ResourceLoader resourceLoader;

    @Bean
    public ChatClient medicalAgentChatClient(
            ChatClient.Builder builder,
            LlmUsageCaptureAdvisor usageAdvisor,
            SessionMemoryAdvisor memoryAdvisor,
            AutoMemoryTools autoMemoryTools) {

        return builder
            // Skills loaded from classpath JAR — no file-system dependency
            .defaultToolCallbacks(
                SkillsTool.builder()
                    .addSkillsResource(
                        resourceLoader.getResource("classpath:skills"))
                    .build())
            // Durable cross-session memory stored at ~/.medexpertmatch/auto-memory/
            .defaultTools(autoMemoryTools)
            .defaultAdvisors(
                usageAdvisor,           // LLM telemetry + Prometheus
                memoryAdvisor)          // sliding-window JDBC session memory
            .build();
    }
}

<dependency>
    <groupId>org.spring-ai-community</groupId>
    <artifactId>spring-ai-agent-utils</artifactId>
    <version>0.9.0</version>
</dependency>

mkdir -p src/main/resources/skills/triage

# src/main/resources/skills/triage/SKILL.md
---
name: triage
description: Assess urgency level for new medical cases and classify
  as CRITICAL, HIGH, MEDIUM, or LOW.
---

## Instructions
Extract chief complaint, check for life-threatening red flags,
return urgencyLevel + rationale as JSON.

ChatClient client = ChatClient.builder(chatModel)
    .defaultToolCallbacks(
        SkillsTool.builder()
            .addSkillsResource(
                resourceLoader.getResource("classpath:skills"))
            .build())
    .build();

String result = client.prompt()
    .user("""
        New case: 58-year-old male, acute chest pain radiating
        to the left arm, diaphoresis, elevated troponin.
        Assess urgency.
        """)
    .call()
    .content();

// LLM activates skill "triage" automatically.
// Returns:
// {
//   "urgencyLevel": "CRITICAL",
//   "rationale": "Classic ACS presentation — immediate cardiology consult required",
//   "redFlags": ["chest pain", "radiation to arm", "diaphoresis", "elevated troponin"]
// }