MedBridge

An intelligent interoperability platform for the laboratory sector, built for the InterSystems IRIS for Health AI Agents contest.

The Problem

Healthcare systems don’t speak the same language — and someone always pays for it.

A laboratory information system (LIS) needs to route exam orders to external systems: a reference lab for exams it can’t perform internally, and an insurance provider for coverage authorization. Each external system has its own protocol, its own payload format, its own error vocabulary. One uses FHIR R4. Another uses flat proprietary JSON. A third uses SOAP. None of them agree on field names, code systems, or error formats.

Today, integrating a new external system takes weeks or months. A developer reads the documentation, writes hardcoded payload builders, maps field by field, tests against the real system, and handles every error case manually. When an integration breaks in production, someone has to read the error, check the source code, check the database, cross-reference the documentation, and make a judgment call. In high-volume labs, this happens dozens of times a day — and every delay is a delay in patient care.

The root causes are always the same:

• No standardization — every system calls the same concept a different name (patient_name, nm_paciente, nomeCli)
• Hardcoded integrations — payload builders are written once and break silently when the contract changes
• Opaque errors — “exam code not found” could mean a bug in the payload, a typo in the catalog, a missing mapping, or a problem on the external system’s side — and there’s no way to know without manual investigation
• Manual onboarding — every new external system requires a new integration project

What MedBridge Does

MedBridge places an AI agent between the LIS and its external systems. The agent handles the full integration lifecycle autonomously:

Intelligent normalization
The agent reads the integration documentation of each external system and builds the correct payload for that system’s contract — without hardcoded field mappings. RefLab expects a FHIR R4 Bundle. VitaCare expects flat proprietary JSON. The agent adapts to each one from documentation alone.

Learning from success
Every successful operation is cached. The agent extracts the payload schema that worked and stores it in IRIS. On subsequent identical requests, it replays the cached schema directly — no LLM call, no documentation lookup, ~55ms response time. The system gets faster as it learns.

Autonomous error diagnosis
When an integration fails, the agent cross-references three sources simultaneously: the source code that built the payload, the integration documentation of the target system, and the LabCore database. It produces a structured diagnosis — origin, confidence score, evidence, and actionable suggestion. If confidence is below 70%, it escalates to AMBIGUOUS rather than guessing. The system knows what it doesn’t know.

Full auditability
Every error is recorded as both a FHIR AuditEvent in IRIS’s native FHIR R4 server and a structured row in a relational table — queryable, traceable, and ready for similarity search against future errors.

Zero-code onboarding of new systems
To add a new external system, drop an integration.md into agents/knowledge/<system>/. The agent indexes it on the first request and starts building correct payloads immediately. No code changes. No new payload builders. No redeployment.

Architecture

Three systems form the integration landscape:

Plus the agent infrastructure:

MCP Servers

The Error Checker Agent uses two MCP servers to gather evidence before diagnosing an error:

python-code-rag is a standalone service that indexes all .py files in the LabCore codebase using AST-based chunking and vector embeddings. The Error Checker queries it with natural language and gets back the relevant functions ranked by similarity score.

RefLab and VitaCare use intentionally different protocols — RefLab speaks FHIR R4, VitaCare speaks proprietary JSON. This forces the agent to handle real-world heterogeneity, not a toy scenario.

Agents

How the Agent Works

Every exam order created in LabCore triggers the agent in a background thread. The agent follows a strict cache-first flow:

POST /service-requests  (LabCore)
        ↓
  trigger_agent()  (background thread)
        ↓
  POST /agent/invoke
        ↓
  check MappingCache  (SQL — no LLM)
        ↓
  HIT  ──→  send_direct  ──→  update use_count  ──→  done  (~55ms, zero LLM cost)
        ↓
  MISS ──→  Doc Reader Agent
                ↓
          check KnowledgeBase for system_target
          if empty → index integration docs on demand
                ↓
          vector search (embedding model)
                ↓
          LLM builds correct payload from docs
                ↓
          send to RefLab or VitaCare
                ↓
          SUCCESS ──→  save to MappingCache  ──→  done
          ERROR   ──→  Error Checker Agent
                            ↓
                      search LabCore codebase (MCP)
                      search integration docs (vector)
                      query LabCore database (MCP)
                            ↓
                      LLM diagnoses error origin:
                        ORIGIN_A  — bug or data issue in LabCore
                        ORIGIN_B  — external system rejected the request
                        CONTRACT  — business rule / contract violation
                        INFRA     — network or system failure
                        AMBIGUOUS — not enough evidence (confidence < 0.70)
                            ↓
                      Reporter Agent
                            ↓
                      write AuditEvent to IRIS FHIR R4
                      write structured row to agent_error_report (SQL)

Key design rule: The LLM is never called on a cache hit. Once the agent has seen an operation succeed, it replays the cached payload schema directly. LLM cost only occurs on the first call per operation, or when an error happens.

Tech Stack

• Python 3.11 + FastAPI 0.115.0 — all services
• SQLAlchemy 2.0 + sqlalchemy-iris 0.11.2 — LabCore + Agent
• IRIS for Health Community Edition — relational + VECTOR database
• LangGraph 0.2.0 — agent graph orchestration
• LiteLLM 1.40.0 — LLM abstraction layer (provider configured via .env, zero code change to swap)
• Reasoning LLM — used by Doc Reader and Error Checker to build payloads and diagnose errors
• Embedding model — used to index integration docs and run vector search
• Docker + Docker Compose — single compose file for all services

Repository Structure

care-sync/
├── docker-compose.yml          # all services
├── .env                        # LLM config — not committed
│
├── core-lab/                   # System A — LabCore (FastAPI + IRIS)
│   ├── models/
│   ├── routes/
│   ├── schemas/
│   └── seed/
│
├── ref-lab/                    # System B — RefLab (FHIR R4 mock)
│   ├── routes/
│   └── simulators/
│
├── vita-care/                  # System C — VitaCare (proprietary mock)
│   ├── routes/
│   └── simulators/
│
├── agents/                     # AI Agent (LangGraph)
│   ├── agents/
│   │   ├── parent.py
│   │   ├── doc_reader.py
│   │   └── error_checker.py
│   ├── tools/
│   │   ├── http_client.py
│   │   ├── knowledge_base.py
│   │   ├── codebase.py         # MCP client for python-code-rag
│   │   └── fhir_writer.py      # writes AuditEvent + error_report to IRIS
│   ├── memory/
│   │   ├── mapping_cache.py
│   │   └── knowledge_base_indexer.py
│   └── knowledge/
│       ├── ref-lab/integration.md
│       └── vita-care/integration.md
│
└── python_code_rag/            # MCP server — semantic search over LabCore code

Running the Project

Prerequisites

• Docker + Docker Compose
• An embedding model accessible via API (for indexing integration docs and running vector search)
• An API key for your chosen reasoning LLM

1. Create the .env file

At the root of care-sync/, create a .env file:

LLM_PROVIDER=          # reasoning LLM
LLM_API_KEY=
LLM_API_BASE=
EMBEDDING_PROVIDER=<provider/model>      # embedding model — for doc indexing and vector search
EMBEDDING_API_BASE=<embedding_api_base>

2. Start all services

docker compose up -d

This starts LabCore, RefLab, VitaCare, the Agent, python-code-rag, and IRIS.

Wait ~30 seconds for IRIS to fully initialize on first boot.

3. Verify services are up

curl http://localhost:8000/health   # LabCore
curl http://localhost:8001/health   # RefLab
curl http://localhost:8002/health   # VitaCare
curl http://localhost:8003/health   # Agent

All should return 200 OK.

4. Run the test suite

Test 1 — cache miss, Doc Reader builds FHIR Bundle (RefLab)

First request with ONC001 (non-performable exam). The agent has no cached schema — it indexes the RefLab integration docs, invokes the LLM to build a FHIR R4 Bundle, sends it, and caches the result on success.

curl -s -X POST http://localhost:8000/service-requests \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "11c5be47-3215-4890-a79f-9c2b2293a85e",
    "practitioner_id": "0f7f838f-5bbd-43b7-951c-02582e4272a3",
    "priority": "ROUTINE",
    "notes": "Test 1 — cache miss, doc_reader builds FHIR Bundle",
    "items": [
      { "exam_code": "ONC001", "exam_name": "Marcadores Tumorais" }
    ]
  }'

Test 2 — cache hit, no LLM invocation (RefLab)

Same operation with different patient/practitioner values and GEN001. The agent finds the cached schema from Test 1, replays it directly — no LLM, ~55ms.

curl -s -X POST http://localhost:8000/service-requests \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "e36e8749-a762-45ea-bd6b-63a5745d6e07",
    "practitioner_id": "8853e3c3-d0f9-469f-ae48-7813dc83b8ec",
    "priority": "URGENT",
    "notes": "Test 2 — cache hit, no doc_reader",
    "items": [
      { "exam_code": "GEN001", "exam_name": "Teste Genetico" }
    ]
  }'

Test 3 — codebase error, Error Checker diagnoses ORIGIN_A (RefLab)

ERR-LOINC is not a valid LOINC code. RefLab rejects with 404 “LOINC code unknown”. The Error Checker searches the LabCore source code, integration docs, and IRIS database, then diagnoses the root cause as ORIGIN_A (LabCore data/mapping issue).

curl -s -X POST http://localhost:8000/service-requests \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "664d2678-29ce-450e-ab50-bd463364ded6",
    "practitioner_id": "35ca797f-5099-479d-91d5-fbe12a125b90",
    "priority": "ROUTINE",
    "notes": "Test 3 — codebase error, unknown LOINC in RefLab",
    "items": [
      { "exam_code": "ERR-LOINC", "exam_name": "Unknown LOINC test (simulator)" }
    ]
  }'

Test 4 — VitaCare covenant expired (VitaCare)

Uses a performable exam (HEM001) so only VitaCare is routed. The covenant_id: "ERR-EXPIRED" payload triggers VitaCare’s ERR-EXPIRED simulator — returns 403 “Covenant plan is not active”. The Error Checker diagnoses the contract violation.

curl -s -X POST http://localhost:8000/service-requests \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "11c5be47-3215-4890-a79f-9c2b2293a85e",
    "practitioner_id": "0f7f838f-5bbd-43b7-951c-02582e4272a3",
    "priority": "ROUTINE",
    "covenant_id": "ERR-EXPIRED",
    "notes": "Test 4 — VitaCare covenant expired, agent routes to vitacare",
    "items": [
      { "exam_code": "HEM001", "exam_name": "Hemograma" }
    ]
  }'

Watch the agent logs after each request:

docker compose logs -f agents

5. IRIS Management Portal

Available at http://localhost:52773/csp/sys/UtilHome.csp
Credentials: _SYSTEM / SYS
Namespace: USER

Error Scenarios

The agent diagnoses four error origins:

Three systems are wired for error simulation:

IRIS Database Tables

All tables live in the USER namespace, SQLUser schema.