Healthcare Companion

AI-powered care for patients and clinicians — triaging symptoms, generating clinical summaries, reconciling medications, and assessing cardiovascular risk, all from live patient data.

Comment

Inspiration

We've both spent more time than we'd like navigating the healthcare system — waiting rooms, repeated intake forms, discharge instructions that raised more questions than they answered, and the constant feeling that information was falling through the cracks between appointments. We knew there had to be a better way. We wanted to build something that automates the fragmented, repetitive parts of healthcare — not just for patients trying to understand what's happening to them, but for the clinicians who need the right information before a patient even walks through the door.

What It Does

Healthcare Companion is a multi-agent AI system that serves both patients and clinicians across every stage of care — from first symptom to post-discharge recovery.

For patients:

  • A single conversational interface that triages symptoms, screens for emergencies, and escalates to 911 when needed
  • Pre-visit preparation so patients never walk into an appointment empty-handed
  • Post-discharge guidance that translates clinical instructions into plain language and tracks recovery milestones

For clinicians:

  • Physician-ready SOAP notes generated from live FHIR data before the encounter begins
  • Medication reconciliation reports that flag high-risk changes between admission and discharge
  • 10-year cardiovascular risk scores with ACC/AHA guideline recommendations, computed from the patient's live record

Everything runs through Compass, an orchestrator that routes queries to the right specialist agent — Primary Health Advisor, Pre-Visit Summarizer, or Care Transition Coordinator — while keeping the agent layer completely invisible to the user. A deterministic ValidateResponse guard screens every reply for privacy violations and speculative language before it reaches anyone.

How We Built It

We built across two technical paths simultaneously.

Path 1 — MCP Server (TypeScript)

A purpose-built clinical tool server exposing 14 tools across six categories: patient data retrieval, new patient registration, wearable integration, diagnosis support, care coordination, and privacy enforcement. All tools connect to a live FHIR R4 server via the Prompt Opinion platform. Three specialist agents and two Compass orchestrator instances were built using Prompt Opinion's BYO agent feature, powered by claude-sonnet-4-6.

Path 2 — Cardiovascular Risk Agent (Python + Google ADK)

An external A2A agent deployed independently and connected to the Prompt Opinion orchestrator via the Agent-to-Agent protocol. It implements the 2013 ACC/AHA Pooled Cohort Equations to compute 10-year ASCVD risk:

$$ P(\text{event}) = 1 - S_0^{\exp\left(\sum \beta_i X_i - \bar{\mu}\right)} $$

The agent pulls total cholesterol, HDL, systolic blood pressure, diabetes status, and smoking history live from FHIR — and detects whether blood pressure is treated or untreated from the active medication list to apply the correct coefficient set. It also supports what-if scenarios, showing clinicians the delta when a risk factor changes (e.g. "what if we lower BP to 120?").

Additional capabilities include Apple Watch / HealthKit integration via GetAppleWatchVitals, which streams real-time heart rate, HRV, SpO2, ECG status, and irregular rhythm flags — with automatic clinical alerts for tachycardia, bradycardia, and low oxygen saturation.

Challenges We Ran Into

Cross-platform A2A integration was the biggest technical hurdle. Connecting an independently deployed Python agent to a TypeScript MCP system through Prompt Opinion required careful alignment of the A2A message schema and FHIR context injection across language boundaries.

Privacy by design was harder than expected. The identity-locking logic — ensuring ValidateResponse always validates against the session-verified patient name and never a name mentioned in a user question — required careful orchestrator prompt engineering and precise tool call sequencing to be airtight.

Keeping clinical logic out of the LLM. The ASCVD calculator, red flag screener, drug interaction checker, and risk indicator assessments are all deterministic and rule-based — not generative. Getting that boundary right, and making sure the LLM deferred to tool output rather than reasoning around it, required significant prompt engineering and testing.

Accomplishments That We're Proud Of

  • End-to-end care journey coverage — one system that handles triage, pre-visit prep, and post-discharge follow-up without the patient ever switching interfaces
  • Cross-language, cross-protocol agent interop — a Python A2A agent and a TypeScript MCP server operating together inside a single orchestrated system
  • Zero-hallucination clinical logic — every safety-critical decision (red flags, drug interactions, risk thresholds) is computed deterministically, not generated
  • A privacy guard that actually works — ValidateResponse blocked cross-patient data requests in live testing before a single character of another patient's data could reach the user
  • Real FHIR data, no mocks — all agents query live patient records at runtime

What We Learned

Building across MCP and A2A in the same system taught us how much protocol design matters at the agent boundary. A2A's structured message schema forced clarity about what context each agent needs — which made the overall system more disciplined than it might have been otherwise.

We also learned that safety in healthcare AI isn't just about the model — it's about what the model is and isn't allowed to decide. The most reliable parts of this system are the ones with no LLM in the loop at all. Deterministic tools for clinical logic, generative AI for language and synthesis — that separation is the architecture.

What's Next for Healthcare Companion

  • Production HealthKit integration — the Apple Watch layer currently uses a documented mock with a defined production swap point; real HealthKit connectivity is the next immediate step
  • Specialist agent expansion — mental health triage, chronic disease management (diabetes, COPD), and pediatric care pathways
  • Bidirectional FHIR writes — updating patient records from agent interactions, not just reading from them
  • Clinician-facing dashboard — a structured view of pending SOAP notes, flagged medication reconciliation issues, and high-risk patients across a panel
  • Expanded A2A agent network — additional external specialist agents (dermatology, oncology risk screening) integrated via A2A alongside the cardiovascular agent

Built With

  • agent-to-agent-protocol-(a2a)
  • apple-healthkit
  • claude-(anthropic)
  • express.js
  • fhir-r4-(hl7)
  • gemini-2.5-flash
  • google-adk
  • model-context-protocol-(mcp)
  • ngrok
  • node.js
  • prompt-opinion
  • python
  • typescript
Share this project:

Updates