IRIS FHIR Agents

A multi-agent clinical AI platform powered by InterSystems IRIS for Health. Features agents for triage, specialist consultation, and pharmacy safety, grounded by IRIS Vector Search RAG.

IRIS FHIR Agents orchestrates four LangChain-powered AI agents that work together to deliver clinical intelligence directly on top of a live FHIR R4 server:

Every agent is grounded by IRIS Vector Search RAG — 50 clinical guidelines from CDC, AHA, FDA, WHO, and KDIGO embedded into IRIS and retrieved semantically at query time. No guideline citation means no recommendation.

Features at a Glance

• Multi-agent orchestration — a zero-temperature LLM router classifies every message and dispatches to the correct agent automatically
• IRIS Vector Search RAG — guidelines stored as VECTOR(DOUBLE, 1536) in IRIS; queried with VECTOR_COSINE for semantic similarity
• Live vitals monitoring — SSE stream writes every reading to FHIR as a coded Observation; critical vitals auto-trigger the Triage Agent
• FHIR Capability Explorer — visual breakdown of what the IRIS FHIR server supports: interaction matrix, resource cards, search param charts
• Full FHIR R4 write path — agents create Observations, ServiceRequests, and MedicationRequests directly in IRIS
• Four-page frontend — consistent sidebar navigation, three themes (Dark / Light / Clinical), live agent network panel
• 10 rich demo patients — covering CAD, HFrEF, T2DM, CKD, sepsis, and complex polypharmacy scenarios

Architecture

Tech Stack

Project Structure

iris-fhir-template/
├── docker-compose.yml
├── .env                          ← your secrets (never commit)
├── Dockerfile                    ← iris 
├── Dockerfile.api                ← application
├── iris.script                   ← Setup the FHIR server
├── merge.cpf                     ← iris
├── module.xml                    ← ZPM 
│
├── src/python/
│   ├── api/
│   │   └── main.py               ← FastAPI server, all HTTP routes
│   │
│   ├── agent/
│   │   ├── config.py             ← centralised configuration
│   │   ├── orchestrator.py       ← LLM router + session management
│   │   ├── triage_agent.py       ← patient intake agent
│   │   ├── specialist_agent.py   ← condition analysis agent
│   │   ├── pharmacy_agent.py     ← medication safety agent
│   │   ├── fhir_agent.py         ← FHIR server exploration agent
│   │   ├── fhir_tools.py         ← shared FHIR R4 tools
│   │   └── knowledge_base.py     ← IRIS Vector Search RAG
│   │
│   └── static/
│       ├── index.html            ← Triage Chat
│       ├── dashboard.html        ← Analytics Dashboard
│       ├── vitals.html           ← Live Vitals Monitor
│       └── fhir_agent.html       ← FHIR Server Agent
│
└── data/
    ├── fhir/
    │   ├── demo_patients.json    ← FHIR Synthetic Data
    │
    └── guidelines/
        └── clinical_rag_guidelines.csv   ← 50 guidelines for RAG

Prerequisites

• Docker Desktop installed and running
• InterSystems IRIS for Health Community Edition (handled by docker-compose)
• An OpenAI API key with access to gpt-4o-mini and text-embedding-3-small

Quick Start

1. Clone the repository

git clone https://github.com/your-username/iris-fhir-agents.git
cd iris-fhir-agents

2. Configure environment variables

cp .env.example .env

Open .env and set your OpenAI API key:

OPENAI_API_KEY=sk-your-real-key-here

All other defaults work out of the box with the Docker setup.

3. Start the platform

docker-compose up -d --build

This starts two containers:

• fhir-template — InterSystems IRIS for Health on ports 32782 / 32783 / 32784
• fhir-triage-api — FastAPI application on port 8000

First startup takes some time while IRIS initialises and the RAG knowledge base embeds 50 guidelines into IRIS Vector Search. Watch the logs:

docker logs fhir-triage-api --tail=50 -f

You should see:

RAG: Loaded 50 guidelines from CSV
RAG: Embedding 50 guidelines into IRIS Vector Search...
RAG: Initialisation complete — 50 new guidelines embedded and stored
INFO:     Uvicorn running on http://0.0.0.0:8000

4. Demo patient data

Synthetic FHIR data is loaded during container build from the data/fhir/demo_patients.json file.

The data can also be loaded using the following cURL command:

curl -X POST http://localhost:32783/fhir/r4 \
  -H "Content-Type: application/fhir+json" \
  -u _SYSTEM:SYS \
  -d @data/fhir/demo_patients.json

5. Open the application

Demo Walkthrough

Triage Chat — try these patients

Type My patient ID is pt-001 to start.

Live Vitals Monitor

Select any patient from the sidebar. Vitals stream every 2 seconds. Occasional critical spikes automatically trigger the Triage Agent — watch the AI Alert Feed panel on the left for the real-time assessment.

FHIR Server Agent

Opens on the FHIR Capability tab by default — a full visual breakdown of what the IRIS server supports. Switch to AI Chat and try:

Which patients have both diabetes and kidney disease?
Show me a complete clinical summary for pt-010
Run this SQL: SELECT COUNT(*) FROM HSFHIR_X0001_S.Patient

How the RAG Works

1. On startup, knowledge_base.py loads clinical_rag_guidelines.csv (50 guidelines)
2. Each guideline is embedded with text-embedding-3-small → 1536-dimensional vector
3. Vectors are stored in IRIS: INSERT INTO RAG.VectorKnowledgeBase ... TO_VECTOR(?, DOUBLE)
4. At query time, the agent’s question is embedded the same way
5. IRIS finds the closest guidelines: VECTOR_COSINE(embedding, TO_VECTOR(?, DOUBLE))
6. Results above 0.1 similarity are returned with relevance scores
7. If IRIS is unavailable, keyword search over the in-memory CSV provides fallback coverage

The same IRIS instance that stores FHIR patient data also stores the clinical guideline vectors — no separate vector database required.

API Reference

Environment Variables

License

MIT License — see https://github.com/mwaseem75/iris-fhir-agents/blob/main/LICENSE for details.

Thanks