Files · After-Hours Pet Emergency Triage Agent for Veterinary Clinics

# After-Hours Pet Emergency Triage Agent for Veterinary Clinics
 
> Automate urgency assessment for after-hours calls, texts, and portal messages to reduce vet burnout and improve client retention.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build a production-grade voice triage agent using the `@reaatech/*` voice-agent-kit package family.
 
## Architecture
 
```
Twilio Phone → WebSocket → TwilioMediaStreamHandler → STT Pipeline → LLM Triage Assessment → TTS Pipeline → Twilio Audio
                                                         │
                                                         └→ Call Session Store → Dashboard UI (Next.js)
```
 
- **Hono HTTP Server** (port 3001) — handles Twilio webhooks, REST API for call data, and text-based triage.
- **WebSocket Server** (shared port) — handles Twilio Media Streams for bidirectional audio streaming.
- **Voice Agent Pipeline** (`@reaatech/voice-agent-core`) — orchestrates STT → MCP → TTS with latency budgeting and cost tracking.
- **STT** (`@reaatech/voice-agent-stt`) — Deepgram Nova-2 for real-time transcription.
- **TTS** (`@reaatech/voice-agent-tts`) — Deepgram Aura for real-time speech synthesis.
- **Telephony** (`@reaatech/voice-agent-telephony`) — Twilio Media Streams handler with barge-in detection.
- **Triage Engine** — LLM-based severity assessment using `ai` + `@ai-sdk/openai` with structured `generateObject`.
- **Next.js Dashboard** (port 3000) — management UI showing call history, severity breakdown, and triage summaries.
- **Observability** — Langfuse for LLM tracing, OpenTelemetry for pipeline metrics.
 
## Prerequisites
 
- Node.js >= 22
- pnpm >= 10
- Twilio account with a phone number capable of Media Streams
- Deepgram API key (for STT/TTS)
- OpenAI API key (for triage LLM)
- Langfuse account (optional, for observability)
 
## Quick Start
 
```bash
pnpm install
cp .env.example .env
# Fill in your API keys in .env
pnpm dev              # starts Hono server (port 3001)
pnpm --filter ./ next dev   # starts Next.js dashboard (port 3000) in another terminal
pnpm test             # runs vitest suite with coverage
```
 
## Configuration
 
| Variable | Required | Default | Description |
|---|---|---|---|
| `DEEPGRAM_API_KEY` | Yes | — | Deepgram API key for STT/TTS |
| `OPENAI_API_KEY` | Yes | — | OpenAI API key for triage LLM |
| `TRIAGE_MODEL` | No | `gpt-5.2-mini` | OpenAI model for triage assessments |
| `LANGFUSE_PUBLIC_KEY` | No | — | Langfuse public key for LLM tracing |
| `LANGFUSE_SECRET_KEY` | No | — | Langfuse secret key for LLM tracing |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | No | `http://localhost:4318/v1/traces` | OpenTelemetry OTLP endpoint |
| `PORT` | No | `3001` | Hono HTTP/WebSocket server port |
| `API_URL` | No | `http://localhost:3001` | Hono API base URL for Next.js proxy |
 
## API Endpoints
 
### Hono Server (port 3001)
 
| Method | Path | Description |
|---|---|---|
| `GET` | `/health` | Health check |
| `POST` | `/twilio/incoming-call` | Twilio webhook — returns TwiML to connect Media Streams |
| `GET` | `/api/calls` | List all call records |
| `GET` | `/api/calls/:callSid` | Get single call record |
| `POST` | `/api/triage` | Text-based triage assessment (body: `{ symptoms, species, sessionId? }`) |
 
### Next.js Dashboard (port 3000)
 
| Method | Path | Description |
|---|---|---|
| `GET` | `/` | Dashboard with call summary and recent calls table |
| `GET` | `/api/health` | Health check |
| `GET` | `/api/calls` | Proxied call list from Hono API |
| `GET` | `/api/calls/:id` | Proxied call detail from Hono API |
 
## Twilio Setup
 
1. Purchase a Twilio phone number with voice capabilities.
2. In the Twilio Console, configure the phone number's "A call comes in" webhook to POST to `https://your-server.com/twilio/incoming-call`.
3. Ensure your server is publicly reachable (use ngrok for local development).
4. The TwiML response will connect the call to the Media Streams WebSocket endpoint.
 
## Project Layout
 
```
app/                  Next.js App Router pages + API route proxies
src/
  types/              TypeScript type definitions
  lib/                Core libraries (pipeline, triage engine, call store, observability)
  services/           Service layer (telephony handler, triage service)
  index.ts            Hono server entry point
tests/                Vitest test suite (mirrors src/)
packages/             API references for every dependency
```
 
## License
 
MIT — see [LICENSE](./LICENSE).