Voice AI Patient Registration Agent
Call a U.S. phone number and talk to Ava, an AI intake coordinator who registers you as a new patient. She collects the standard demographic dataset by talking with you, checks each field, reads it all back, saves it to Postgres, and can book your first appointment. Call again and she recognizes your phone number and offers to update your record instead.
Live demo
Seed data: two fictional patients, Jane Doe (212) 555-0101 and Carlos Rivera (305) 555-0123. Call and give Jane's number to try the returning-patient flow (her DOB is 03/14/1985).
Architecture
┌──────────────┐ PSTN ┌─────────────────────────────────────────┐
Caller ──┤ Phone number ├────────►│ Vapi (managed) │
└──────────────┘ │ Deepgram STT → GPT-4o → ElevenLabs TTS │
│ system prompt + tool schemas (ours) │
└───────────────┬─────────────────────────┘
│ HTTPS webhook (x-webhook-secret)
│ tool-calls / status-update / end-of-call-report
┌──────────────────────────────────────────────────▼──────────────────────────┐
│ FastAPI service (this repo), one deployable │
│ │
│ app/voice/ webhook.py → tools.py ─┐ app/api/ /patients, /calls │
│ (telephony/LLM glue, prompt) │ (REST, JSON envelope) │
│ ▼ │ │
│ app/services/ (business logic, shared) ◄─┘ │
│ app/validation.py (one rulebook for API + agent) │
│ ▼ │
│ app/models.py SQLAlchemy ─► PostgreSQL (SQLite local)│
│ │
│ /dashboard (static HTML reading the REST API) │
└─────────────────────────────────────────────────────────────────────────────┘
Separation of concerns
| Layer | Location | Responsibility |
|---|
| Telephony, STT, TTS, turn-taking | Vapi (managed) | Phone number, audio, barge-in, endpointing |
| Conversation design | app/voice/prompt.py, app/voice/assistant.py | System prompt, voice/model config, as code |
| Agent actions | app/voice/tools.py | Tool schemas the LLM sees and their handlers |
| Webhook transport | app/voice/webhook.py | Auth, parse Vapi messages, log, persist transcripts |
| REST API | app/api/ | HTTP ↔ service translation, envelope, status codes |
| Business logic | app/services/ | Patient CRUD, soft delete, call logs, appointments |
| Validation | app/validation.py | Normalizers used by both the API schemas and the agent |
| Persistence | app/models.py, app/db.py | Schema, constraints, indexes |
The voice agent does not write to the DB itself. It calls the same service functions as POST /patients/PUT /patients/:id, so phone and API data go through identical validation. The spec allows calling the REST API or "the same service layer"; I used the service layer to skip a pointless HTTP hop inside one process.
A call, end to end
- Vapi answers and speaks the first message. The caller talks, Deepgram transcribes, and GPT-4o decides what to say or which tool to call.
- Once it has the phone number, the agent calls
lookup_patient_by_phone. If the number matches a record, it says "It looks like we already have a record for Jane Doe. Would you like to update your information instead?" and checks the caller's DOB before changing anything.
- After the required fields (plus any optional fields the caller opts into), it calls
validate_patient_info. Server-side errors come back as plain-English messages per field, and the agent re-asks only for those fields.
- It reads everything back in short groups and waits for an explicit confirmation before calling
save_patient.
- If the save works, it says "You're all set, Jane!" and offers to book an appointment (
get_appointment_slots / book_appointment), then says goodbye and calls endCall.
- Vapi sends
end-of-call-report, and the transcript and summary are stored in call_logs, linked to the patient.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
