集成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.克隆存储库

git clone https://github.com/vyshnavi-ops/zippygo_agent_with_mcp_oct30th.git
cd zippygo_agent_with_mcp_oct30th

2.安装Python依赖项

pip install -r requirements.txt

3.环境配置

创建一个 .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

🏃‍♂️ 快速开始

地方发展

# Run the local testable version
python local_testable_assistant.py start

# Or run the production version locally
python main.py start

生产部署

# 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) │
                    └─────────────────┘

数据流

令牌生成：Lambda发布特定于设备的房间令牌
房间创建：每个设备都有单独的房间(device_{hash})
代理自动加入：代理在用户连接时自动加入
语音处理：使用OpenAI的实时STT/TTS
工具执行：MCP服务器处理航班预订操作
数据持久层：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证书管理

部署步骤

配置AWS凭据
更新 production.tfvars 与你的价值观
部署基础设施:

   cd infrastructure
   terraform init
   terraform apply -var-file="production.tfvars"

构建和推送容器:

   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：基本指标端点

🧪 测试

局部测试

# 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

生产测试

# 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服务运行状况

获取帮助

问题:
文档：检查内联代码注释和文档字符串
日志：启用DEBUG日志记录以进行详细的故障排除

🔄 版本历史

v2.0.0版本：多房间架构，集成MCP
v1.0.0：首次生产发布
v0.9.0版本：具有基本功能的Beta版本

🙏 致谢

LiveKit团队：卓越的实时通信框架
开放人工智能：强大的语音处理能力
亚马逊云服务：用于强大的云基础设施
达夫尔：适用于综合航班预订API
社区：用于反馈和贡献

______________________________________________________________________

内置❤️ 提供无缝的语音航班预订体验

zippygo agent with MCP oct30th

快速接入

详细介绍