Spaces:
Running
Running
File size: 9,867 Bytes
59ba41d 2f49513 59ba41d 2f49513 59ba41d |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 |
# Healthcare Telehealth Nurse Agent
This agent is a 24/7 AI voice nurse for existing patients. It authenticates callers, retrieves mock patient profiles (medications, allergies, recent visits), recognizes common symptoms, performs contextual triage using decision rules, offers self‑care guidance, escalates urgent cases, and books appointments. All interactions aim to be clear, compassionate, and brief.
**✨ Recent Improvements**: Tool docstrings and system prompts have been significantly enhanced with:
- Clear step-by-step instructions for each tool
- Explicit guidance on the secret question authentication flow
- Detailed examples showing expected inputs/outputs
- Better error handling instructions
- Improved conversation flow structure
## What it does
- Authenticate the caller (name + DOB + MRN last‑4 or secret answer)
- Look up patient profile, allergies, medications, recent visits, preferred pharmacy
- Recognize symptoms (e.g., "I have a headache") and identify red flags
- Risk stratify and triage (self‑care, soon, urgent) using rules in `mock_data/triage_rules.json`
- Provide tailored advice based on symptoms and medication history
- Escalate urgent cases with clear instructions
- Offer scheduling with available providers from `mock_data/providers.json`
- Confirm preferred pharmacy for prescriptions if needed
## How to use (typical flow)
1. Start by stating your name.
2. Verify identity: provide DOB and either MRN last‑4 or your secret answer. If a secret question is returned, answer it.
3. Describe your symptoms in your own words.
4. The agent will ask brief, focused follow‑ups (one question at a time), provide guidance, and book if needed.
## Tool Call Flow Diagram
```
┌─────────────────────────────────────────────────────────────┐
│ 1. GREETING & NAME │
│ User: "My name is John Marshall" │
│ → find_patient(full_name="John Marshall") │
│ ← {patient_id: "pt_jmarshall"} │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 2. IDENTITY VERIFICATION (CRITICAL) │
│ Agent: "Please confirm your date of birth" │
│ User: "January 1st, 1960" │
│ → verify_identity(dob="January 1st, 1960") │
│ ← {verified: false, question: "What is your favorite │
│ color?", needs: ["mrn_last4_or_secret"]} │
│ │
│ Agent: "For security, what is your favorite color?" │
│ User: "Blue" │
│ → verify_identity(dob="...", secret_answer="Blue") │
│ ← {verified: true, needs: []} │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 3. PROFILE RETRIEVAL │
│ → get_patient_profile_tool() │
│ ← {allergies: ["Penicillin"], │
│ medications: [{name: "Acetaminophen", ...}], ...} │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 4. SYMPTOM COLLECTION & TRIAGE │
│ Agent: "What brings you in today?" │
│ User: "I have a headache and feel tired" │
│ → triage_symptoms_tool(symptoms_text="headache and │
│ fatigue, no red flags") │
│ ← {risk: "self_care", advice: "Try rest...", │
│ red_flags: []} │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 5. APPOINTMENT BOOKING (if needed) │
│ → list_providers_tool() │
│ ← [{provider_id: "prov_smith_md", ...}] │
│ │
│ → get_provider_slots_tool(provider_id="prov_smith_md") │
│ ← ["2025-10-09T08:30:00", "2025-10-09T16:00:00"] │
│ │
│ Agent: "Tomorrow at 8:30am or 4pm. Which works?" │
│ User: "8:30am" │
│ → schedule_appointment_tool(slot_iso="2025-10-09T08:30")│
│ ← {appointment_id: "A-abc123", status: "booked"} │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 6. PHARMACY CONFIRMATION │
│ → get_preferred_pharmacy_tool() │
│ ← {name: "CVS", address: "1010 El Camino Real..."} │
│ Agent: "Keep pharmacy at 1010 El Camino Real?" │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 7. CALL LOGGING & CLOSING │
│ → log_call_tool(notes="...", triage_json="...") │
│ ← {logged: true, log_id: "L-xyz789"} │
│ Agent: "If symptoms worsen, seek urgent care. Take care"│
└─────────────────────────────────────────────────────────────┘
```
**Key Points:**
- **Step 2 is the most critical**: The secret question requires a TWO-call pattern
- **Always retrieve profile (Step 3)** before giving medical advice
- **Triage (Step 4)** determines whether to proceed with booking or direct to ER
- **Logging (Step 7)** documents the entire encounter
## Example conversation
- Agent: Welcome back to our clinic. I’m your nurse assistant. May I have your full name?
- You: John Marshall.
- Agent: Thanks, John. Please confirm your date of birth and either your MRN last‑4 or answer to your secret question.
- You: January 1st, 1960. MRN last‑4 is 0001.
- Agent: Thank you. You’re verified. What’s going on today?
- You: I have a headache and feel really fatigued.
- Agent: I’m sorry you’re feeling that way. Any red flag symptoms like worst headache of your life, head injury, stiff neck, weakness, vision changes, seizure, or fever over 102°F?
- You: No, none of those.
- Agent: Thanks for checking. You’re on acetaminophen as needed and have a penicillin allergy. Since symptoms are mild with no red flags, try hydration, rest, and acetaminophen as directed. Would you like a telehealth appointment in the next day or two?
- You: Yes, please.
- Agent: I can book with Alex Chang, NP. Next openings are today at 8:00 pm, or tomorrow at 8:30 am or 4:00 pm. Which do you prefer?
- You: Tomorrow at 8:30 am.
- Agent: Booked. I’ll send details to your phone ending in 0101. Should we keep the pharmacy at 1010 El Camino Real, Santa Clara for any prescriptions?
- You: Yes, that’s fine.
- Agent: Great. I’ve logged your symptoms, advice provided, and appointment. If anything worsens—especially fever over 102°F, neck stiffness, confusion, weakness, vision loss, or severe headache—seek urgent care or call emergency services.
## Mock data
- Patients: `mock_data/patients.json`
- Providers: `mock_data/providers.json`
- Pharmacies: `mock_data/pharmacies.json`
- Triage rules: `mock_data/triage_rules.json`
## Notes
- The agent prioritizes empathy and brevity. It asks one question at a time and avoids medical jargon.
- All data are mock fixtures for demo purposes only and are not real medical records.
|