Files · AWS Bedrock Lead Intake for Small Business Growth

# AWS Bedrock Lead Intake for Small Business Growth
 
**Convert phone calls and web forms into structured, qualified leads—automatically routed to your CRM with AI voice analysis and document extraction.**
 
SMBs lose up to 40% of leads because calls go unanswered and form submissions languish in email inboxes. This reference implementation demonstrates a complete lead intake pipeline that captures voice calls via Twilio, transcribes them with Deepgram, classifies intent using agent-mesh-classifier, extracts structured fields with agent-memory-extraction, and routes qualified leads to your CRM (e.g., HubSpot) via agent-handoff-routing. A budget engine and circuit breaker keep AWS Bedrock costs visible and services resilient under load.
 
## Architecture
 
```
Twilio Call/Web Form
    │
    ▼
Twilio Webhook ──► Deepgram Transcription
    │                   │
    ▼                   ▼
agent-mesh-classifier ◄── Transcript
    │                   │
    ▼                   ▼
agent-memory-extraction ──► Structured Fields
    │
    ▼
agent-handoff-routing ──► HubSpot CRM
    │
    ├── agent-budget-engine (cost tracking + soft/hard caps)
    ├── circuit-breaker-agents (failure isolation)
    └── Langfuse (observability/tracing)
```
 
## Tech Stack
 
- **Runtime:** Node.js 22+, TypeScript (strict mode, NodeNext resolution)
- **Server:** Express 5 (JSON/URL-encoded body parsing, multipart file upload)
- **AI/ML:**
  - AWS Bedrock (Claude Sonnet 4, Haiku 4, Opus 4 via Converse API)
  - Deepgram Nova-3 (speech-to-text transcription)
- **Agent Framework:**
  - `@reaatech/agent-mesh-classifier` — intent classification
  - `@reaatech/agent-memory-extraction` — structured field extraction
  - `@reaatech/agent-handoff-routing` — capability-based CRM routing
  - `@reaatech/agent-budget-engine` — LLM budget enforcement
  - `@reaatech/circuit-breaker-agents` — failure isolation
  - `@reaatech/agent-eval-harness-suite` — extraction quality validation
- **Document Processing:** unpdf (PDF text extraction)
- **Observability:** Langfuse
- **Testing:** Vitest 4, MSW, aws-sdk-client-mock
 
## Quick Start
 
```bash
pnpm install
cp .env.example .env
# Fill in your AWS credentials, Deepgram API key, Twilio credentials, etc.
pnpm dev        # starts server with tsx watch
```
 
## API Endpoints
 
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/health` | Health check — returns `{ status: "ok" }` |
| `POST` | `/webhook/twilio` | Twilio call webhook — accepts `CallSid`, `RecordingUrl`, `From`, `To` |
| `POST` | `/intake` | Direct intake endpoint — accepts `{ transcript, ... }` JSON body |
| `POST` | `/forms/upload` | PDF form upload — `multipart/form-data` with `file` field |
 
## Lead Intake Flow
 
1. **Twilio Webhook** — Receives call events, validates signature, fetches recording URL, passes audio to Deepgram
2. **Deepgram Transcription** — Nova-3 model with smart formatting, diarization, and utterance detection
3. **Intent Classification** — `agent-mesh-classifier` determines lead type (sales inquiry, support, other)
4. **Field Extraction** — `agent-memory-extraction` extracts contact name, phone, email, company, budget, timeline
5. **CRM Routing** — `agent-handoff-routing` selects best CRM agent and dispatches to HubSpot API
6. **Cost Tracking** — `agent-budget-engine` records every LLM call and enforces daily budget caps
7. **Circuit Breaker** — `circuit-breaker-agents` isolates failing downstream services (5 failures → open, 30s recovery)
 
## Environment Variables
 
See `.env.example` for all required variables. Key ones:
 
- `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` — Bedrock auth
- `DEEPGRAM_API_KEY` — Speech-to-text
- `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER` — Call webhook
- `HUBSPOT_API_KEY` — CRM dispatch
- `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY` — Observability
- `LLM_DAILY_BUDGET` — Cost cap (default: $50)
 
## Production Deployment
 
- Run on AWS EC2 or Lambda with API Gateway
- Use IAM roles instead of access keys for Bedrock in production
- Twilio webhook URL must be publicly accessible
- Replace InMemorySpendStore with a persistent store (e.g., DynamoDB, Redis)
- Configure Langfuse host for self-hosted deployments
 
## License
 
[MIT](LICENSE)