StewardAI

Intelligent antibiotic stewardship over FHIR — an AI-assisted workflow for pharmacists and clinicians to review microbiology cultures and recommend safer, narrower antibiotics when guidelines allow.

Built for Agents Assemble — The Healthcare AI Endgame (hackathon). This repository contains the MCP tool server, an A2A agent (Google ADK) that orchestrates stewardship workflows, and FHIR R4 demo data with a small mock FHIR API for local testing.

---

Why this exists

When a broad-spectrum antibiotic is started, the lab eventually identifies the organism and susceptibilities. Clinical stewardship expects a timely review to de-escalate to a narrower drug when appropriate — reducing resistance pressure, side effects, and cost. StewardAI automates gathering FHIR context (active antibiotics, cultures, allergies, renal function) and produces structured stewardship recommendations, including optional FHIR Task creation for documentation.

---

Repository layout

Path	Purpose
mcp-server/	FastMCP server: FHIR queries + Gemini-powered generate_stewardship_recommendation, exposed over streamable HTTP
a2a-agent/	A2A agent (FastAPI + Google ADK): agent card, sessions, calls into the MCP server
fhir-data/	Demo patient bundles (patient_*.json) and mock_server.py — minimal FHIR R4 read/search API
.specify/features/	Feature spec, plan, and tasks (product requirements)

---

Architecture

flowchart LR
  subgraph clients [Clients]
    PO[Prompt Opinion / A2A clients]
  end
  subgraph agent [A2A agent]
    ADK[Google ADK steward agent]
  end
  subgraph mcp [MCP server]
    Tools[FHIR tools + recommendation engine]
  end
  subgraph data [FHIR]
    FHIR[FHIR server or mock]
  end
  PO --> ADK
  ADK -->|MCP JSON-RPC / streamable HTTP| Tools
  Tools -->|HTTPS + patient context| FHIR

Loading

• MCP tools accept SHARP-style context per call: fhir_url, optional fhir_token, and patient_id.
• Prompt Opinion can inject FHIR context via A2A metadata; locally you point tools at the mock FHIR base URL.

---

MCP tools (overview)

The MCP server exposes stewardship-oriented tools, including:

• get_active_antibiotics — active antibiotic-related medications
• get_culture_results / parse_sensitivity_profile — microbiology and susceptibilities
• check_patient_allergies — allergy cross-check
• get_renal_function — labs / eGFR for dose context
• get_infection_context — condition / infection framing
• generate_stewardship_recommendation — structured recommendation (Pydantic-validated)
• create_stewardship_task — POST a FHIR Task with the recommendation summary

See mcp-server/server.py for signatures and behavior.

---

Demo patients (FHIR bundles)

Bundled JSON files under fhir-data/ illustrate scenarios such as straightforward de-escalation, penicillin allergy vs suggested beta-lactams, and renal / resistance-aware cases:

• patient_chen.json — UTI / de-escalation scenario
• patient_patel.json — pneumonia + allergy awareness
• patient_johnson.json — additional stewardship scenario

The mock server loads patient_*.json (not test_*.json) at startup.

---

Prerequisites

• Python 3.12+
• uv (recommended) or pip
• Google AI (Gemini) API key — Google AI Studio
• Optional: ngrok (or similar) if you need HTTPS public URLs for integrations

Copy each service’s .env.example to .env and set secrets there. Never commit .env.

---

Local development

1. Mock FHIR server

From fhir-data/ (requires FastAPI + Uvicorn — install globally or use uv with inline packages):

cd fhir-data
uv run --with fastapi --with uvicorn python mock_server.py

Alternatively, with any Python 3.12+ environment: pip install fastapi uvicorn then python mock_server.py.

Default base URL: http://localhost:7777 (override with FHIR_MOCK_PORT).

2. MCP server

From mcp-server/:

cd mcp-server
copy .env.example .env
# Edit .env: GEMINI_API_KEY, optional FHIR_SERVER_URL for dev
uv sync
uv run python server.py

Default: http://0.0.0.0:8000 — streamable HTTP MCP (PORT, HOST in .env).

3. A2A agent

From a2a-agent/:

cd a2a-agent
copy .env.example .env
# Set GEMINI_API_KEY, GOOGLE_API_KEY, MCP_SERVER_URL, PUBLIC_URL for your setup
uv sync
uv run python main.py

Default agent port: 8001 (PORT). Set PUBLIC_URL and MCP_SERVER_URL to public HTTPS bases when using Prompt Opinion or tunnels (not localhost).

---

Tests

cd mcp-server
uv sync --group dev
uv run pytest

---

Docker / Hugging Face Spaces

Both mcp-server/Dockerfile and a2a-agent/Dockerfile use uv, default PORT=7860 for Spaces-style hosting. Run container with the same environment variables as local .env where applicable.

---

Contributing & license

Issues and PRs welcome via GitHub. Add a short note in your PR if you change MCP contracts or FHIR assumptions so demos stay aligned with the spec under .specify/features/.

---

Disclaimer

This software is for research, education, and hackathon demonstration. It is not medical advice and must not replace professional clinical judgment or institutional protocols.