Handoff Assistant — AI-Powered Clinical Signout with MedGemma

The Problem

Clinical handoffs are the most dangerous moments in patient care. When one physician ends their shift and another takes over, critical information gets lost. Communication failures during handoffs contribute to an estimated 80% of serious medical errors and up to 1,844 patient deaths per year in the U.S. alone. Today, residents spend 15–20 minutes per patient manually assembling handoff notes from scattered EHR data — a tedious, error-prone process under time pressure.

What We Built

Handoff Assistant is a multi-agent system powered by MedGemma 27B (text) that transforms raw patient records into structured, evidence-grounded I-PASS handoff briefs in under 60 seconds. It doesn't just summarize — it reasons about clinical significance, links every claim to its source data, detects inconsistencies between narrative notes and structured chart data, and surfaces actionable next steps for the receiving physician.

The system is built on the Google Agent Development Kit (ADK) and orchestrates five specialized agents, each leveraging MedGemma as its clinical reasoning backbone:

Agent Architecture

Agent	Role	How MedGemma Is Used
Writer Agent	Produces a structured I-PASS handoff draft (illness severity, patient summary, action list, situation awareness, synthesis)	MedGemma interprets raw clinical data — labs, vitals, medications, notes — and generates a clinically appropriate handoff with prioritized findings and specific lab values
Provenance Router	Maps every clinical claim to its source FHIR resource (lab result, medication order, clinical note)	MedGemma classifies each claim and routes it to the correct evidence type (Observation, MedicationRequest, DocumentReference), enabling clickable source citations
Consistency Agent	Compares what narrative notes say vs. what structured chart data shows	Deterministic fact extraction + MedGemma-powered reasoning to flag contradictions (e.g., "note says renal function stable" but creatinine is rising 29%)
Evidence Companion	Retrieves external clinical guidelines and literature for top-priority issues	Summarizes retrieved evidence in clinical context using MedGemma's medical knowledge
Verifier Agent	Enforces safety constraints: schema validation, citation completeness, no prescription language	Ensures every claim has a source reference or is marked uncertain; flags unsafe language patterns

Key Differentiating Features

1. Claim-to-Source Hyperlinks — Click any claim in the handoff and see the exact lab value, medication, or note line backing it. Every assertion is traceable to a FHIR-style resource reference with timestamp and display value.

2. Proactive Mismatch Detection — The system compares narrative notes against structured chart data and surfaces contradictions before they cause harm. Example: a note says "renal function improving" but creatinine has risen 29% — the system flags this with citations to both the text claim and the lab trend.

3. Clinical Significance Reasoning — MedGemma doesn't just detect changes; it reasons about clinical importance. A creatinine change of 0.7 to 0.8 within normal range is described as "may be clinically minor," while a hemoglobin drop from 12.6 to 7.5 on anticoagulants triggers a bleeding concern with specific action items.

4. Delta + Contingencies — The handoff includes what changed since the last signout (new meds, lab trends, vital shifts) and if-then contingency plans (e.g., "If hemoglobin drops below 7, consider transfusion and hold anticoagulant").

5. Interactive Q&A — After generating the handoff, physicians can ask follow-up questions ("Why are the labs abnormal?", "Show me the evidence", "What should I watch for overnight?") and get answers grounded in the patient's data.

End-to-End Pipeline

Patient Record
    |
    v
[1. Load Record] --> [2. Format] --> [3. Signal Extraction]
                                        (trends, conflicts)
    |
    v
[4. Writer Agent]         MedGemma drafts I-PASS handoff
    |
    v
[5. Provenance Router]    MedGemma maps claims --> FHIR citations
    |
    v
[6. Consistency Check]    Note text vs. structured chart data
    |
    v
[7. Evidence Companion]   External guidelines for top issues
    |
    v
[8. Synthesis + Verifier] Schema validation, safety checks
    |
    v
Structured I-PASS Handoff Brief (JSON)

The orchestrator runs an 8-step pipeline in sequence, maintaining a full execution trace with timing for each step. The entire pipeline completes in ~37 seconds per patient.

Evaluation (MIMIC-IV Cohort)

We evaluated the system against real clinical cases from MIMIC-IV, comparing AI-generated handoffs to actual clinician-written signout notes:

Metric	Baseline (Human Notes)	Agent (MedGemma)
I-PASS checklist coverage	0%	50%
High-risk misses per patient	2.0	1.0
Evidence grounding (claims with citations)	—	100%
Consistency contradictions flagged	—	0 false positives
Verification pass rate	—	100%
Time saved per patient	—	~16 minutes

Dashboard UI

A React-based dashboard provides a resident-friendly interface:

• Patient selector with search-by-ID
• I-PASS structured layout (Illness severity, Patient summary, Action list, Situation awareness, Synthesis)
• Role-based views (Resident gets full clinical detail; Nurse gets compact actions + watch-fors)
• Clickable citations panel with source data for each claim
• External evidence section with guideline links
• Chat panel for follow-up clinical questions

Tooling

The agent system uses 15+ purpose-built tools organized by function:

Category	Tools
Data ingestion	RecordLoaderTool, RecordFormatterTool
Signal extraction	TrendAnalyzerTool, ConflictDetectorTool
Provenance	ClaimExtractorTool, FHIRResourceLookupTool, CitationLinkerTool
Consistency	NoteSummaryIngestTool, DataFactBuilderTool, ConsistencyCheckerTool
Evidence	ExternalEvidenceRetrievalTool, ExternalEvidenceSummarizerTool
Synthesis	MedGemmaHandoffWriterTool, DeltaTool, ContingencyTool

---

Tech Stack

Python 3.10+, Google ADK, MedGemma 27B (text), FastAPI, React + TypeScript + Vite

Setup (virtual env + pyenv best practice)

1. Python version (optional with pyenv)

pyenv install 3.10.13   # if not already installed
pyenv local 3.10.13     # uses .python-version in repo

2. Create and activate virtual environment

Python 3.10+ required (ADK and Google libs). Use the setup script to recreate .venv with a supported version:

./scripts/setup_venv.sh   # uses python3.10/3.11/3.12 if available
# Or manually:
python -m venv .venv
source .venv/bin/activate   # macOS/Linux

3. Install dependencies

pip install -r requirements.txt

4. Environment variables (see Environment variables below)

5. Run

# Direct pipeline (prints handoff JSON)
python run_handoff.py --case 0

# Orchestrator agent (chat)
adk run handoff_agent

Option 1 – Single server (simplest):

pip install fastapi uvicorn
cd frontend && npm install && npm run build
cd .. && uvicorn api.server:app --reload --port 8001
# Open http://localhost:8001

Option 2 – Dev mode (hot reload):

uvicorn api.server:app --reload --port 8001   # Terminal 1
cd frontend && npm run dev                     # Terminal 2
# Open http://localhost:5173

Environment variables

Variable	When to set
MEDGEMMA_VERTEX_ENDPOINT	Vertex endpoint after deploying MedGemma 27B from Model Garden
GOOGLE_API_KEY	API key (AI Studio)
HANDOFF_DATA_DIR	Optional: path to dir with patient_records.pkl (default: ./data)

With MedGemma endpoint set, run gcloud auth application-default login for Vertex.

---

Evaluation

Run the evaluation script against the MIMIC-IV cohort:

python3 scripts/eval_mimic.py \
  --manifest data/mimic_eval_manifest_20.csv \
  --out-dir eval_runs \
  --results-csv eval_runs/results.csv \
  --review-minutes 2 \
  --reuse-existing

Results are written to eval_runs/results.csv and eval_runs/results_20.summary.json.

---

Repository Structure

ai-for-life/
├── api/server.py              # FastAPI backend (patients, handoff, ask, cache)
├── handoff_agent/agent.py     # ADK root_agent entry point
├── run_handoff.py             # CLI entry for pipeline
├── src/
│   ├── orchestrator.py        # 8-step workflow runner
│   ├── config.py              # Model/env configuration
│   ├── agents/
│   │   ├── orchestrator_agent.py        # ADK orchestrator with step tools
│   ├── tools/
│   │   ├── record_tools.py       # Load + format patient records
│   │   ├── signal_tools.py       # Trend analysis + conflict detection
│   │   ├── provenance_tools.py   # FHIR lookup + citation linking
│   │   ├── consistency_tools.py  # Note vs. chart comparison
│   │   ├── evidence_tools.py     # Evidence resolution
│   │   ├── external_evidence_tools.py  # Guideline retrieval
│   │   ├── synthesis_tool.py     # Final handoff assembly
│   │   ├── delta_tools.py        # Changes since last signout
│   │   └── contingency_tools.py  # If-then plans
│   └── schemas/models.py        # TypedDict definitions
├── frontend/                    # React + Vite dashboard
├── scripts/
│   ├── eval_mimic.py            # Evaluation against MIMIC-IV
│   └── run_precompute.py        # Pre-process patient records
├── data/
│   ├── latest/                  # Patient records + processed data
│   ├── baseline_notes/          # Clinician handoff notes for comparison
│   └── checklists/              # I-PASS evaluation checklists
└── eval_runs/                   # Evaluation results + step traces