集成MCP的ZippyGo语音代理
使用LiveKit代理框架构建的用于航班预订的生产就绪AI语音代理,具有多房间架构、MCP(模型上下文协议)集成和全面的AWS基础设施。
🚀 特性
核心能力
- 🎤 语音优先接口:与OpenAI Whisper STT和TTS的自然对话流
- ✈️ 航班预订:完成端到端的航班搜索、选择和预订
- 💳 支付处理:通过NMI网关集成实现安全支付处理
- 🏢 多房间建筑:针对并发用户的基于设备的房间隔离
- 🔌 MCP集成:用于外部工具集成的模型上下文协议服务器
- ☁️ AWS生产就绪:完整的ECS/Fargate部署和监控
技术架构
- LiveKit代理框架:v1.2.9,带有最新插件
- 多用户支持:每个房间一个代理,完全隔离数据
- 实时通信:基于WebRTC的语音流
- 数据库持久性:DynamoDB用于会话和预订存储
- 基础设施即代码:完整的地形配置
- 健康监测:全面的健康检查和指标
📋 先决条件
- python:3.9+(建议3.11)
- Node.js:18+(用于Lambda函数)
- AWS帐户:具有适当的权限
- OpenAI API密钥:用于语音处理
- LiveKit服务器:自托管或云实例
🛠️ 安装
1.克隆存储库```bash
git clone https://github.com/vyshnavi-ops/zippygo_agent_with_mcp_oct30th.git
cd zippygo_agent_with_mcp_oct30th
### 2.安装Python依赖项```bash
pip install -r requirements.txt
3.环境配置
创建一个 .env 项目根目录中的文件:```env
LiveKit Configuration
LIVEKIT_URL=wss://your-livekit-server.com
LIVEKIT_API_KEY=your_api_key
LIVEKIT_API_SECRET=your_api_secret
OpenAI Configuration
OPENAI_API_KEY=sk-your_openai_key
AWS Configuration
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
Flight Booking APIs
DUFFEL_API_KEY=your_duffel_key
NMI_API_KEY=your_nmi_key
NMI_USERNAME=your_nmi_username
NMI_PASSWORD=your_nmi_password
MCP Server
MCP_BASE_URL=https://flights-mcp.zippygo.ai/mcp
Application Settings
ENVIRONMENT=development
LOG_LEVEL=INFO
## 🏃♂️ 快速开始
### 地方发展```bash
# Run the local testable version
python local_testable_assistant.py start
# Or run the production version locally
python main.py start
生产部署```bash
Deploy infrastructure
cd infrastructure
terraform init
terraform plan -var-file="production.tfvars"
terraform apply -var-file="production.tfvars"
Build and deploy containers
docker build -t zippygo-voice-agent .
Push to ECR and update ECS service
## 📁 项目结构```
├── 📄 README.md # Project documentation
├── 📄 main.py # Production agent entry point
├── 📄 assistant.py # Core agent implementation
├── 📄 local_testable_assistant.py # Local development version
├── 📄 requirements.txt # Python dependencies
├── 📄 Dockerfile # Container configuration
├── 📄 .env # Environment variables (template)
├── 📄 __init__.py # Python package initialization
├── 📄 task-def-clean.json # ECS task definition
├── 📄 project_tech_description.md # Technical architecture details
├── 📄 ZippyGo-Architecture-Flow.md # System architecture flow
│
├── 📁 infrastructure/ # Terraform Infrastructure as Code
│ ├── 📄 main.tf # Main Terraform configuration
│ ├── 📄 ecs-voice-agent-v2.tf # ECS service definition
│ ├── 📄 alb.tf # Application Load Balancer
│ ├── 📄 dynamodb.tf # DynamoDB tables
│ ├── 📄 lambda.tf # Lambda functions
│ ├── 📄 variables.tf # Terraform variables
│ ├── 📄 outputs.tf # Terraform outputs
│ └── 📄 *.tf # Additional AWS resources
│
├── 📁 lambda_v2/ # Token Service Lambda Function
│ ├── 📄 index.js # Lambda function handler
│ ├── 📄 package.json # Node.js dependencies
│ └── 📄 README.md # Lambda deployment guide
│
└── 📁 utils/ # Utility Modules
├── 📄 __init__.py # Package initialization
├── 📄 db.py # Database operations (DynamoDB)
├── 📄 dynamodb.py # DynamoDB client and operations
├── 📄 logging.py # Centralized logging configuration
├── 📄 config.py # Environment configuration management
├── 📄 redis_cache.py # Redis caching utilities
└── 📄 s3_storage.py # S3 storage operations
🏗️ 架构概述
多房间建筑```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Device A │ │ Device B │ │ Device C │
│ Room: dev_123 │ │ Room: dev_456 │ │ Room: dev_789 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ LiveKit Server │
│ (Load Balanced)│
└─────────────────┘
│
┌─────────────────┐
│ ECS Fargate │
│ Voice Agents │
│ (Auto-scaling) │
└─────────────────┘
### 数据流
1. **令牌生成**:Lambda发布特定于设备的房间令牌
1. **房间创建**:每个设备都有单独的房间(`device_{hash}`)
1. **代理自动加入**:代理在用户连接时自动加入
1. **语音处理**:使用OpenAI的实时STT/TTS
1. **工具执行**:MCP服务器处理航班预订操作
1. **数据持久层**:DynamoDB存储会话和预订数据
## 🔧 配置
### 环境变量
|变量|描述|必填|默认|
|----------|-------------|----------|---------|
| `LIVEKIT_URL` |livekit服务器websocket URL|✅ | - |
| `LIVEKIT_API_KEY` |LiveKit API密钥|✅ | - |
| `LIVEKIT_API_SECRET` |LiveKit API机密|✅ | - |
| `OPENAI_API_KEY` |用于语音处理的OpenAI API密钥|✅ | - |
| `DUFFEL_API_KEY` |用于航班搜索的Duffel API密钥|✅ | - |
| `NMI_API_KEY` |NMI支付网关API密钥|✅ | - |
| `MCP_BASE_URL` |MCP服务器端点|❌ | `https://flights-mcp.zippygo.ai/mcp` |
| `AWS_REGION` |DynamoDB的AWS区域|❌ | `us-east-1` |
| `LOG_LEVEL` |日志记录级别|❌ | `INFO` |
### MCP服务器配置
该代理与外部MCP服务器集成,用于航班预订操作:
- **搜索航班**:实时航班可用性
- **获取优惠详情**:详细的航班信息
- **座位选择**:交互式座位地图
- **支付处理**:安全支付处理
- **预订确认**:订单创建和管理
## 🚀 部署
### AWS基础架构
该项目包括用于AWS部署的完整Terraform配置:
#### 核心服务
- **ECS Fargate**:容器化代理部署
- **应用程序负载平衡器**:交通分布
- **DynamoDB**:会话和预订存储
- **拉姆达**:令牌生成服务
- **路线53**:DNS管理
- **国际计算机学会**:SSL证书管理
#### 部署步骤
1. **配置AWS凭据**
1. **更新 `production.tfvars`** 与你的价值观
1. **部署基础设施**:```bash
cd infrastructure
terraform init
terraform apply -var-file="production.tfvars"
- 构建和推送容器:```bash
docker build -t zippygo-voice-agent .
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin .dkr.ecr.us-east-1.amazonaws.com
docker tag zippygo-voice-agent:latest .dkr.ecr.us-east-1.amazonaws.com/zippygo-voice-agent:latest
docker push .dkr.ecr.us-east-1.amazonaws.com/zippygo-voice-agent:latest
### 健康监测
该代理包括全面的健康检查:
- **`/health`**:整体系统健康状况
- **`/health/ready`**:ECS准备就绪探针
- **`/health/live`**:ECS的生存性探测
- **`/metrics`**:基本指标端点
## 🧪 测试
### 局部测试```bash
# Run local development version
python local_testable_assistant.py start
# Test with LiveKit CLI
lk room create --name test-room
lk token create --room test-room --identity test-user
生产测试```bash
Test token generation
curl -X POST "https://your-api-gateway/prod/token" \
-H "Content-Type: application/json" \
-d '{"deviceId":"test_device_123"}'
Test health endpoints
curl https://your-alb-url/health
curl https://your-alb-url/health/ready
```
📊 监控
CloudWatch指标
- ECS服务指标:CPU、内存、任务计数
- ALB指标:请求计数、延迟、错误
- Lambda指标:调用、持续时间、错误
- DynamoDB指标:读/写容量,节流
日志记录
- 结构化日志记录:JSON格式,便于解析
- 日志级别:调试、信息、警告、错误
- 上下文跟踪:会话ID、设备ID、房间名称
- 错误跟踪:详细的错误消息和堆栈跟踪
🔒 安全
数据保护
- 付款数据:日志/存储中不包括敏感支付信息
- 会话隔离:设备/房间之间的完全数据隔离
- 加密:所有在传输和静止时加密的数据
- 访问控制:IAM角色具有最小特权原则
API安全
- 仅限HTTPS:所有端点都使用TLS加密
- CORS配置:适当的跨来源资源共享
- 速率限制:防止虐待
- 输入验证:全面的输入净化
🤝 贡献
- 分叉存储库
- 创建要素分支:
git checkout -b feature/amazing-feature - 提交更改:
git commit -m 'Add amazing feature' - 推送到分支:
git push origin feature/amazing-feature - 打开拉取请求
开发指南
- 遵循现有的代码风格和模式
- 添加新功能的测试
- 更新变更文档
- 确保所有健康检查通过
📝 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🆘 支持
常见问题
代理未连接
- 验证LiveKit服务器是否正在运行且可访问
- 检查
LIVEKIT_URL,LIVEKIT_API_KEY,以及LIVEKIT_API_SECRET - 确保与LiveKit服务器的网络连接
语音处理问题
- 验证
OPENAI_API_KEY有效且有足够的学分 - 检查浏览器/应用程序中的音频设备权限
- 监控OpenAI API速率限制
付款处理错误
- 验证NMI凭据是否正确
- 检查支付网关连接
- 查看NMI仪表板中的事务日志
数据库连接问题
- 验证AWS凭据和权限
- 检查DynamoDB表是否存在和配置
- 监控AWS服务运行状况
获取帮助
- 问题: GitHub问题
- 文档:检查内联代码注释和文档字符串
- 日志:启用DEBUG日志记录以进行详细的故障排除
🔄 版本历史
- v2.0.0版本:多房间架构,集成MCP
- v1.0.0:首次生产发布
- v0.9.0版本:具有基本功能的Beta版本
🙏 致谢
- LiveKit团队:卓越的实时通信框架
- 开放人工智能:强大的语音处理能力
- 亚马逊云服务:用于强大的云基础设施
- 达夫尔:适用于综合航班预订API
- 社区:用于反馈和贡献
内置❤️ 提供无缝的语音航班预订体验