HealthCallPilot

HealthCallPilot is a voice-agent system for autonomous appointment booking. It combines:

• Real outbound provider calls (ElevenLabs + Twilio)
• Agentic tool calling (calendar checks, booking confirmation, outcomes)
• Swarm simulation for parallel provider outreach demos
• Calendar-integrated cancel/reschedule and waitlist/callback tracking

Current Scope

This repository is currently centered on one backend service:

• backend/communication-service (FastAPI, deployed on Cloud Run)

Frontend is a Vite + React app located at repository root (App.tsx, components/, utils/).

What Works

• Single-call real booking flow (/initiate-call)
• Live call updates over WebSocket (/ws)
• Post-call transcript webhook and transcript download
• Swarm demo modes:
  • swarm_agents (/demo/swarm-elevenlabs-agents)
  • swarm_scale (/demo/mock-swarm-a2a)
• Calendar integration:
  • check/add/update/delete
• Cancel and reschedule via agent:
  • /initiate-cancel-call
  • /initiate-reschedule-call
  • /tools/cancel-appointment
  • /tools/reschedule-appointment
• Waitlist and callback intelligence:
  • structured outcomes in report_outcome
  • /waitlist/* and /callback/* registry endpoints
  • live websocket updates: waitlist_update, callback_update

Architecture

Frontend

• React 18 + TypeScript + Vite
• Main screens:
  • Quick Book / Swarm (App.tsx, components/SwarmDashboard.tsx)
  • Call Provider dashboard (components/CallProviderDashboard.tsx)
  • Calendar dashboard (components/CalendarDashboard.tsx)

Backend

• FastAPI service in backend/communication-service/main.py
• In-memory session state for active calls/campaigns and waitlist/callback registries
• Google Calendar helpers in backend/communication-service/calendar_utils.py

Integrations

• ElevenLabs Conversational AI
• Twilio outbound PSTN
• Google Calendar API
• Google Maps/Distance Matrix for travel estimates

Repository Layout

healthcallpilot/
├── App.tsx
├── components/
├── utils/
├── backend/
│   ├── communication-service/
├── test/
│   ├── E2E_FINAL_CHECKLIST.md
│   └── smoke_test_3_modes.txt
└── README.md

Environment

Frontend (.env in repo root)

• VITE_COMMUNICATION_SERVICE_URL (optional; defaults to deployed Cloud Run URL)
• VITE_GOOGLE_CALENDAR_CLIENT_ID (optional; used by utils/googleCalendar.ts)

Backend (backend/communication-service)

See env.example for template values. Core keys:

• ELEVENLABS_API_KEY
• ELEVENLABS_AGENT_ID
• ELEVENLABS_PHONE_NUMBER_ID
• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_PHONE_NUMBER
• GOOGLE_API_KEY
• GOOGLE_MAPS_KEY
• CALENDAR_TOKEN_JSON (for server-side calendar access)

Do not commit real credentials.

Local Development

1) Frontend

npm install
npm run dev

2) Backend (communication-service)

cd backend/communication-service
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8080

Deploy (Cloud Run)

From backend/communication-service:

gcloud run deploy communication-service \
  --source . \
  --region europe-west1 \
  --allow-unauthenticated \
  --set-env-vars "GOOGLE_CLOUD_PROJECT=gen-lang-client-0765479704,ELEVENLABS_AGENT_ID=agent_0801kgwz0c3mf09ajgvh1q6x7pyx" \
  --set-secrets "GOOGLE_API_KEY=GOOGLE_API_KEY:latest,GOOGLE_MAPS_KEY=GOOGLE_MAPS_KEY:latest,ELEVENLABS_API_KEY=ELEVENLABS_API_KEY:latest,ELEVENLABS_PHONE_NUMBER_ID=ELEVENLABS_PHONE_NUMBER_ID:latest,TWILIO_PHONE_NUMBER=TWILIO_PHONE_NUMBER:latest,TWILIO_AUTH_TOKEN=TWILIO_AUTH_TOKEN:latest,TWILIO_ACCOUNT_SID=TWILIO_ACCOUNT_SID:latest,DEMO_PHONE_NUMBER=DEMO_PHONE_NUMBER:latest,CALENDAR_TOKEN_JSON=CALENDAR_TOKEN_JSON:latest"

Minimal Smoke Checks

BASE="https://communication-service-345003514655.europe-west1.run.app"

curl -s "$BASE/health"
curl -s "$BASE/openapi.json" | grep -E "initiate-cancel-call|initiate-reschedule-call|tools/cancel-appointment|tools/reschedule-appointment|waitlist|callback"

ElevenLabs Tooling

Expected webhook tools:

• check_calendar -> /tools/check-calendar
• confirm_slot -> /tools/confirm-slot
• report_outcome -> /tools/report-outcome
• cancel_appointment -> /tools/cancel-appointment
• reschedule_appointment -> /tools/reschedule-appointment

For reliability, include call_id in tool payloads for all call-linked actions.

End-to-End Test Plan

Use:

• test/E2E_FINAL_CHECKLIST.md

This checklist covers:

• booking regression
• multilingual regression
• cancel/reschedule via agent
• waitlist/callback live updates
• transcript and calendar endpoint regression