Referral Loop Guardian

Inspiration

Referral loops are one of those healthcare problems that look simple from the outside but become messy very quickly in the real world.

A patient can be referred to a specialist, but the referral may quietly stall because the packet is incomplete, the appointment was never scheduled, the specialist note came back but was not reviewed, or nobody is sure who owns the next step. These gaps are not always dramatic at first, but they can lead to delayed follow-up, duplicated work, frustrated patients, and missed accountability.

We built Referral Loop Guardian to make that hidden referral state visible. Instead of letting referral information stay scattered across notes, orders, tasks, and status fields, the agent turns it into a clear, human-reviewable handoff: what is happening, what is missing, who should act, and what the safest next step is.

What it does

Referral Loop Guardian is a patient-scoped healthcare agent focused on closing pulmonology referral loops.

For a selected patient, it reviews referral context and determines where the referral currently stands. It can identify whether the referral is blocked, still open, scheduled, waiting on a specialist note, completed, or has no active referral. It also checks whether the referral packet appears ready for pulmonology review by looking for key items such as the referral order, PCP note, chest imaging, smoking history, medication list, and pulmonary function test or spirometry information.

The agent then applies grounded pulmonology referral rules, parses relevant notes, identifies missing packet items, assigns the likely owner of the next step, and drafts patient-safe outreach when communication is needed.

The final output is not an autonomous clinical decision. It is a structured JSON handoff and checklist for human review, designed to help care teams quickly understand:

• the current referral status
• what is missing or blocking progress
• who should take action
• what should happen next
• what evidence the agent used
• whether patient outreach is appropriate

The goal is simple: make referral follow-up easier to review, safer to coordinate, and harder to lose.

How we built it

We built Referral Loop Guardian as a BYO Agent inside Prompt Opinion, using patient-scoped context so the agent works around a specific patient rather than a generic prompt.

The workflow uses synthetic FHIR patients and the FHIR Context Extension to provide patient-specific clinical and referral data. An external MCP server powers the workflow tools that inspect referral state, check packet readiness, apply pulmonology-specific rules, and return structured outputs.

We designed the agent around a grounded rules collection for pulmonology referrals, so the system does not invent requirements or make unsupported clinical decisions. Instead, it maps the available referral context against explicit rules and produces a JSON response that can be checked, displayed, and reviewed.

We also built an embedded MCP App checklist surface so the output is not just a block of text. The checklist helps surface the referral state, missing items, owner, and next action in a way that feels usable for real coordination work.

The project was built with:

• Prompt Opinion
• FHIR
• FHIR Context Extension
• MCP Apps
• External MCP server
• TypeScript
• Docker
• JSON Schema

Challenges we ran into

The hardest part was making the agent useful without making it unsafe.

Referral workflows often sit between clinical care and administrative coordination. That means the agent has to help identify blockers and next steps, but it should not behave like an autonomous clinician. We had to be careful about how the system described urgency, ownership, missing information, and patient outreach.

Another challenge was modeling referral states clearly. A referral is not simply “done” or “not done.” It may be blocked because required information is missing, open because nobody scheduled it yet, waiting because a specialist note has not returned, or incomplete because the note came back but no one acted on it. Capturing those states in a structured way took iteration.

We also had to connect several moving parts: Prompt Opinion, patient-scoped FHIR context, the BYO Agent, the external MCP server, MCP workflow tools, structured JSON outputs, grounded pulmonology rules, and the embedded MCP App interface. Getting those pieces to work together in a coherent healthcare workflow was one of the biggest engineering challenges.

Accomplishments that we're proud of

We are proud that Referral Loop Guardian became more than a simple chatbot. It is a working healthcare workflow prototype that combines patient-scoped context, FHIR data, MCP tools, structured outputs, and a reviewable checklist interface.

We are especially proud of three things:

First, the agent keeps a clear safety boundary. It does not try to diagnose, treat, or make final clinical decisions. It focuses on referral coordination and produces outputs for human review.

Second, it turns messy referral information into a structured handoff. Instead of giving a vague summary, it returns specific fields such as referral status, packet readiness, missing items, next action, owner, and patient outreach guidance.

Third, we were able to learn a new healthcare AI platform and connect multiple technical components into a working prototype within a short build period.

What we learned

This project taught us that healthcare AI is not only about answering medical questions. Some of the most useful AI systems may be the ones that help reduce coordination failures, organize scattered information, and make human review easier.

We learned more about referral workflows, closed-loop care coordination, FHIR context, MCP Apps, external tool servers, structured JSON outputs, and the importance of grounding agents in explicit rules.

We also learned that safety in healthcare AI is not just about refusing dangerous answers. It is about designing the workflow so the agent has the right role from the beginning: support the care team, show its reasoning through structured evidence, and keep humans in control of the final action.

What's next for Referral Loop Guardian

Pulmonology is the first specialty, but the same pattern could be reused across other referral types.

The next step would be to expand Referral Loop Guardian into a configurable referral safety layer for multiple specialties, where each specialty has its own packet requirements, referral states, ownership rules, and outreach templates.

We would also improve the checklist interface, add more referral scenarios, test the agent against a wider set of synthetic patients, and make the rules easier for healthcare organizations to customize.

Long term, Referral Loop Guardian could help healthcare teams find stalled referrals before they become missed follow-ups, reduce administrative back-and-forth, and make referral ownership clearer across the care journey.

Built With

• docker
• fhir
• json-schema
• mcp-apps
• promptopinion
• typescript