Files · Databricks Voice Agent for After-Hours Property Maintenance Intake

# Databricks Voice Agent for After-Hours Property Maintenance Intake
 
> A voice agent that handles after-hours property maintenance calls, classifies requests, and creates work orders in AppFolio.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade voice AI systems with the `@reaatech/*` package family.
 
## Architecture
 
Twilio Call → Incoming Webhook → TwiML `<Connect><Stream>` → WebSocket Media → `@reaatech/voice-agent-telephony` handler → `DeepgramSTTProvider` (STT via `@reaatech/voice-agent-stt`) → `Pipeline` → `classifyIntent` (Databricks LLM via `@ai-sdk/openai-compatible`) → `DecisionEngine` (`@reaatech/confidence-router-core`: route/clarify/fallback) → `dispatchWorkOrder` (AppFolio REST via `@reaatech/agent-handoff` with retry) → `DeepgramTTSProvider` (TTS response via `@reaatech/voice-agent-tts`)
 
## REAA Packages
 
| Package | Role | Purpose |
|---------|------|---------|
| `@reaatech/voice-agent-core` | foundation | Pipeline orchestrator, session manager, latency enforcement |
| `@reaatech/voice-agent-stt` | foundation | Deepgram STT integration via `DeepgramSTTProvider` |
| `@reaatech/voice-agent-tts` | foundation | Deepgram TTS integration via `DeepgramTTSProvider` |
| `@reaatech/voice-agent-telephony` | supporting | Twilio Media Streams WebSocket handler |
| `@reaatech/confidence-router-core` | supporting | Decision engine for intent classification routing |
| `@reaatech/agent-handoff` | supporting | Agent handoff protocol with retry utilities |
| `@reaatech/session-continuity` | supporting | Session lifecycle manager for multi-turn conversations |
 
## Third-Party Packages
 
- `@deepgram/sdk` — Deepgram speech recognition API
- `twilio` — Twilio voice API and TwiML generation
- `@ai-sdk/openai-compatible` — OpenAI-compatible LLM provider (used for Databricks model serving)
- `zod` — Schema validation
- `langfuse` — LLM observability and tracing
 
## Environment Variables
 
| Variable | Description |
|----------|-------------|
| `DEEPGRAM_API_KEY` | Deepgram API key for STT/TTS |
| `TWILIO_ACCOUNT_SID` | Twilio account SID |
| `TWILIO_AUTH_TOKEN` | Twilio auth token |
| `TWILIO_PHONE_NUMBER` | Twilio phone number for inbound calls |
| `DATABRICKS_HOST` | Databricks workspace URL |
| `DATABRICKS_TOKEN` | Databricks personal access token |
| `DATABRICKS_SERVING_ENDPOINT` | Model serving endpoint name |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
| `LANGFUSE_HOST` | Langfuse host URL |
| `APPOFOLIO_CLIENT_ID` | AppFolio API client ID |
| `APPOFOLIO_CLIENT_SECRET` | AppFolio API client secret |
| `APPOFOLIO_BASE_URL` | AppFolio API base URL |
| `WS_PORT` | WebSocket server port for Twilio Media Streams |
| `WS_URL` | WebSocket URL template for TwiML Stream directive |
 
## Twilio Configuration
 
1. Buy a Twilio phone number in the [Twilio Console](https://console.twilio.com).
2. Set the Voice webhook URL to `https://your-host/api/calls/incoming`.
3. Set the Status callback URL to `https://your-host/api/calls/status`.
4. Configure the Media Streams WebSocket at `wss://your-host/media`.
 
## Databricks Configuration
 
1. Deploy a chat model (e.g. DBRX-Instruct or Llama) to a [Model Serving Endpoint](https://docs.databricks.com/en/machine-learning/model-serving/index.html).
2. Create a [Personal Access Token](https://docs.databricks.com/en/dev-tools/auth/pat.html).
3. Set `DATABRICKS_HOST`, `DATABRICKS_TOKEN`, and `DATABRICKS_SERVING_ENDPOINT`.
 
## Running Locally
 
```bash
pnpm install
cp .env.example .env    # fill in your credentials
pnpm dev                # starts Next.js dev server + WebSocket server
```
 
## Testing
 
```bash
pnpm test        # vitest run with coverage
pnpm typecheck   # TypeScript type checking
pnpm lint        # ESLint
```
 
## License
 
MIT — see [LICENSE](./LICENSE).