LiveKit AI 代理
此仓库包含两个LiveKit语音AI代理，展示了不同的功能和集成方式。
概述
basic_livekit_agent.py- 一个以《Valorant》为主题的语音助手，具备比赛搜索和训练赛预约等功能工具mcp_livekit_agent.py- 集成MCP（模型上下文协议）服务器的高级语音代理
先决条件
所需API密钥
创建一个 .env 在项目根目录中创建文件，并设置以下环境变量：
# OpenAI API Key (required for both agents)
OPENAI_API_KEY=your_openai_api_key_here
# Deepgram API Key (required for both agents)
DEEPGRAM_API_KEY=your_deepgram_api_key_here
# LiveKit credentials (get from your LiveKit Cloud dashboard)
LIVEKIT_URL=your_livekit_url_here
LIVEKIT_API_KEY=your_livekit_api_key_here
LIVEKIT_API_SECRET=your_livekit_api_secret_here
# Optional: LLM model choice (defaults to gpt-4.1-mini for MCP agent)
LLM_CHOICE=gpt-4.1-miniPython 环境
# Install dependencies
pip install -r requirements.txt
# Or using uv (recommended)
uv sync代理1：基础Valorant语音代理
基本代理展示了：
- 与功能工具的语音交互
- 按地图搜索比赛
- 筛选预订功能
- 简单的对话式人工智能
运行基本代理
uv run basic_livekit_agent.py console特点/特性
- 比赛搜索“给我显示Ascent上的比赛”
- 加入对战练习（或：加入排位赛）“我想以凤凰的身份加入比赛asc001，我是一名决斗者。”
- 时间查询“现在几点了？”
代理2：MCP LiveKit代理
MCP代理展示如下：
- 与外部MCP服务器的集成
- 通过模型上下文协议增强工具功能
- 高级语音管道配置
- 实时转录
MCP Agent 的先决条件
关键的；严重的在运行MCP LiveKit代理之前，您必须启动Docker MCP网关：
docker mcp gateway --transport=streaming --port=80此命令启动代理连接的MCP网关 http://localhost:80/mcp。
运行MCP代理
uv run mcp_livekit_agent.py console特点
- MCP服务器集成连接到外部MCP服务器以增强功能
- 高级语音处理流水线使用Deepgram Nova-2语音转文本（STT）和OpenAI文本转语音（TTS）技术，搭配Echo语音
- 转录实时对话转录
- 增强指令专门用于Airbnb MCP服务器工具的使用（忽略robots.txt）
建筑学
基本代理架构
User Voice Input → Deepgram STT → OpenAI LLM → Function Tools → OpenAI TTS → Voice OutputMCP代理架构
User Voice Input → Deepgram STT → OpenAI LLM → MCP Servers → Function Tools → OpenAI TTS → Voice Output配置选项
语音管道设置
两种代理都支持以下配置：
- STT（注：STT在不同上下文中有不同含义，此处为一般翻译，具体含义需根据上下文确定）Deepgram Nova-2模型
- LLMOpenAI GPT模型（可通过
LLM_CHOICE环境变量) - TTS（Text-to-Speech）即“文本转语音”技术OpenAI TTS（文本转语音）支持多种声音
- VAD（Voice Activity Detection，语音活动检测）Silero语音活动检测
MCP服务器配置
MCP代理通过HTTP连接到MCP服务器，地址为：
mcp_servers=[mcp.MCPServerHTTP(url="http://localhost:80/mcp")]故障排除
常见问题
- MCP网关连接失败
- 确保Docker MCP网关正在运行： docker mcp gateway --transport=streaming --port=80 - 检查端口80是否可用且未被阻塞
- API密钥错误
- 请验证所有API密钥是否已正确设置 .env - 检查API密钥权限和配额
- 语音管道问题
- 确保已授予麦克风权限 - 如果音频质量不佳，请尝试使用不同的语音模型进行测试
记录日志
两个代理都包含全面的日志记录功能。通过以下方式设置日志级别：
logging.basicConfig(level=logging.INFO) # or DEBUG for verbose output发展
添加新功能工具
通过装饰方法来添加新工具 @function_tool：
@function_tool
async def my_new_tool(self, context: RunContext, param: str) -> str:
"""Tool description for the LLM."""
# Implementation here
return "Tool result"MCP服务器集成
要添加新的MCP服务器，请更新 mcp_servers 代理配置中的列表：
mcp_servers=[
mcp.MCPServerHTTP(url="http://localhost:80/mcp"),
# Add additional MCP servers here
]许可证
此项目作为LiveKit语音代理的一个示例实现提供。