IRIS Health FHIR Agentic Demo

Agentic AI for Healthcare using InterSystems IRIS for Health + CrewAI

This is a reference demo showing how event-driven, explainable, auditable Agentic AI can be applied to real healthcare workflows.

What This Demo Shows

When an abnormal laboratory result is received (FHIR Observation), an automated multi-agent workflow:

📊 Collects patient clinical context (previous labs, medications, conditions)
📚 Retrieves evidence from clinical guidelines using RAG (Vector DB)
🧠 Performs structured clinical reasoning
💡 Generates follow-up recommendations
💾 Persists explainable reasoning and evidence in IRIS

This is not a chatbot. This is event-driven, explainable, auditable Agentic AI for healthcare.

Architecture Overview

Key steps:

FHIR Observation → POSTed to IRIS FHIR server
Interaction Strategy → Detects clinical event
Interoperability Production → Orchestrates workflow
Business Operation → Calls Agentic AI REST service (FastAPI)
Agents Execute → Context retrieval, guideline search, reasoning
Results Return → Structured JSON back to IRIS
Persistence → SQL tables store cases, recommendations, evidence
Publishing → FHIR DiagnosticReport created and stored

For detailed architecture, design principles, and execution models, see https://github.com/intersystems-ib/iris-health-fhir-agentic-demo/blob/main/ARCHITECTURE.md.

Prerequisites

🐳 Docker Desktop - For running InterSystems IRIS for Health
🐍 Python 3.11+ - For the CrewAI agent workflow
🔑 OpenAI API key - For GPT-4o and text-embedding-3-small
🔌 VS Code REST Client extension (recommended) - For testing FHIR endpoints

🚀 Quick Start

1. 📦 Setup Environment

Clone the repository and create a Python virtual environment:

git clone https://github.com/intersystems-ib/iris-health-fhir-agentic-demo
cd iris-health-fhir-agentic-demo

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

2. ⚙️ Configure Environment Variables

Copy the example environment file and add your OpenAI API key:

cp .env.example .env

Edit .env and set your OPENAI_API_KEY:

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini

IRIS_HOST=localhost
IRIS_PORT=1972
IRIS_NAMESPACE=INTEROP
IRIS_USERNAME=superuser
IRIS_PASSWORD=SYS

EMBEDDING_MODEL=my-openai-config

3. 🐳 Start IRIS Container

Build and run the IRIS container:

docker-compose build
docker-compose up -d

4. 🏥 Initialize FHIR Server

Create a FHIR R4 repository in IRIS using the Management Portal:

Open the IRIS Management Portal: http://localhost:52773/csp/sys/UtilHome.csp
Login with credentials: superuser / SYS
Navigate to: Health → INTEROP → FHIR Server Management → Add New Server
Create a new FHIR Server endpoint:
- Namespace: INTEROP
- Name: demo
- FHIR Version: `R4``
- URL: /interop/fhir/r4
- Advanced Configuration → Data Organization Strategy: clinicalai.fhirserver.InteractionsStrategy
- This strategy class will capture Observation POST events and trigger the Interoperability Production

5. 👤 Load Sample FHIR Data

Load the sample patient bundle (Jose Garcia) into the FHIR server.

Using curl

curl -X POST http://localhost:52773/interop/fhir/r4/ \
  -u "superuser:SYS" \
  -H "Content-Type: application/fhir+json" \
  -d @iris/init/fhir/JoseGarcia.json | jq

Or using IRIS Management Portal:

This loads:

Patient: Jose Garcia (MRN-1000001)
Conditions: Hypertension, CKD Stage 3
Medications: Ibuprofen (NSAID), Lisinopril
Lab Results: 3 historical creatinine observations

6. 🗄️ Initialize SQL Schema and Vector Database

Create SQL Tables

Navigate to IRIS SQL Explorer (System Explorer → SQL → INTEROP) and run the schema initialization:

LOAD SQL FROM FILE '/app/iris/init/schema.sql' DIALECT 'IRIS' DELIMITER ';'

This creates:

clinicalai_data.GuidelineChunks - Vector DB for clinical guidelines
clinicalai_data.Cases - AI evaluation results
clinicalai_data.CaseRecommendations - Recommended actions
clinicalai_data.CaseEvidences - Evidence citations

Configure IRIS Embedding Model

Create the IRIS EMBEDDING configuration for OpenAI:

INSERT INTO %Embedding.Config (Name, Configuration, EmbeddingClass, VectorLength, Description)
VALUES (
  'my-openai-config',
  '{"apiKey":"your-openai-api-key-here", "sslConfig": "llm_ssl", "modelName": "text-embedding-3-small"}',
  '%Embedding.OpenAI',
  1536,
  'OpenAI text-embedding-3-small for clinical guidelines'
)

Important: Replace your-openai-api-key-here with your actual OpenAI API key.

Ingest Clinical Guidelines

Run the ingestion script to embed clinical guidelines into the vector database:

python iris/vector/ingest_guidelines.py

This script:

Reads guideline documents from iris/vector/guidelines/
Chunks them for RAG (800 chars, 150 overlap)
Stores chunks in GuidelineChunks table
Generates embeddings using IRIS EMBEDDING() function

Note: Add your own clinical guideline documents (.txt, .md, .markdown) to iris/vector/guidelines/ before running the script.

7. ▶️ Run the Demo

Start the FastAPI Service

First, start the CrewAI FastAPI service that will be called by the IRIS Business Operation:

./run_api.sh

The service will start on http://localhost:8000. You should see output indicating the server is running.

Note: Keep this terminal running. Open a new terminal for the next steps.

Option A: Using the Gradio UI (Recommended for Demo)

Launch the interactive web interface:

python run_ui.py

Then open your browser to http://localhost:7860

The UI provides an intuitive interface to:

Enter lab values and trigger the AI workflow
View real-time agent progress and reasoning
See recommendations and evidence citations

Note: The API service must be running (see previous step) for the UI to work.

Option B: Trigger the Workflow via FHIR POST

Recommended: Use VS Code REST Client

Open https://github.com/intersystems-ib/iris-health-fhir-agentic-demo/blob/main/samples/demo.http in VS Code and execute the “POST new observation” request. This will POST an abnormal lab result that triggers the AI workflow.

Alternative: Using curl

curl -X POST http://localhost:52773/interop/fhir/r4/Observation \
  -u "superuser:SYS" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Observation",
    "status": "final",
    "category": [{"coding": [{"code": "laboratory"}]}],
    "code": {
      "coding": [{"system": "http://loinc.org", "code": "2160-0"}],
      "text": "Serum creatinine"
    },
    "subject": {"reference": "Patient/1"},
    "effectiveDateTime": "2026-01-08T10:00:00Z",
    "valueQuantity": {"value": 2.1, "unit": "mg/dL"},
    "interpretation": [{"coding": [{"code": "H"}]}]
  }' | jq

This will automatically:

Trigger the IRIS Interoperability Production
Execute the Business Process (FollowUpAI)
Call the FastAPI service to run CrewAI agents
Persist results to SQL tables
Publish a FHIR DiagnosticReport

View Results

Interoperability Production Messages:

View message trace in IRIS Management Portal:

Navigate to: Interoperability → View → Messages or click here in [Message Viewer][http://localhost:52773/csp/healthshare/interop/EnsPortal.MessageViewer.zen?$NAMESPACE=INTEROP&]

For detailed project structure and architecture, see https://github.com/intersystems-ib/iris-health-fhir-agentic-demo/blob/main/ARCHITECTURE.md.

SQL Query Results:

-- View all AI evaluation cases (latest first)
-- Shows: Patient, Observation, Risk Level, Confidence, Reasoning Summary
SELECT * FROM clinicalai_data.Cases ORDER BY CreatedAt DESC

-- View all recommendations generated by the AI
-- Shows: Action Type, Action Description, Timeframe
SELECT * FROM clinicalai_data.CaseRecommendations

-- View all clinical evidence used (explainability)
-- Shows: Guideline citations, similarity scores, text excerpts
SELECT * FROM clinicalai_data.CaseEvidences

FHIR DiagnosticReport:

Use https://github.com/intersystems-ib/iris-health-fhir-agentic-demo/blob/main/samples/demo.http or curl:

curl -u "superuser:SYS" \
  "http://localhost:52773/interop/fhir/r4/DiagnosticReport?subject=Patient/1" | jq

🛠️ Technologies Used

InterSystems IRIS for Health - Clinical data platform with FHIR support
CrewAI 0.95.0 - Multi-agent orchestration framework
OpenAI GPT-4o - Language model for clinical reasoning
Python 3.11+ - Runtime environment
FHIR R4 - Healthcare data standard

🎯 Key Design Principles

✅ Explainability First

Every recommendation includes:

Patient context used
Clinical guidelines referenced (with citations)
Reasoning explanation
Confidence level
Audit trail in IRIS

🏥 Healthcare-Realistic

Conservative language (decision support, not diagnosis)
Evidence-based recommendations
Proper disclaimers
Demo data only (no real patients)

🎓 Demo-Oriented

Simple architecture (no microservices, no message brokers)
Explainable live in 15 minutes
Clear audit trail via SQL queries
Not production-ready (reference implementation)

🔗 Accessing IRIS

🖥️ IRIS Management Portal

URL: http://localhost:52773/csp/sys/UtilHome.csp
Username: superuser
Password: SYS
Namespace: INTEROP

🌐 FHIR REST API

Base URL: http://localhost:52773/interop/fhir/r4
Authentication: Basic Auth (superuser:SYS)

Use https://github.com/intersystems-ib/iris-health-fhir-agentic-demo/blob/main/samples/demo.http for demo requests or https://github.com/intersystems-ib/iris-health-fhir-agentic-demo/blob/main/samples/fhir.http for comprehensive FHIR testing. Alternatively, use curl:

# Get all patients
curl -u "superuser:SYS" http://localhost:52773/interop/fhir/r4/Patient | jq

# Get specific observation
curl -u "superuser:SYS" http://localhost:52773/interop/fhir/r4/Observation/1 | jq

🤝 Contributing

This is a reference demo. Contributions that maintain simplicity and explainability are welcome.

Guidelines:

Keep the architecture simple and demo-friendly
Maintain explainability as a core principle
Follow the design constraints in https://github.com/intersystems-ib/iris-health-fhir-agentic-demo/blob/main/ARCHITECTURE.md
Ensure changes can be explained in a live demo setting

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

Inspired by the InterSystems customer-support-agent-demo.

iris-health-fhir-agentic-demo Awaiting Review