Live Kit AI Agent

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-mini

Python 环境

# 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 Output

MCP代理架构

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")]

故障排除

常见问题

1. MCP网关连接失败

- 确保Docker MCP网关正在运行： docker mcp gateway --transport=streaming --port=80 - 检查端口80是否可用且未被阻塞

1. API密钥错误

- 请验证所有API密钥是否已正确设置 .env - 检查API密钥权限和配额

1. 语音管道问题

- 确保已授予麦克风权限 - 如果音频质量不佳，请尝试使用不同的语音模型进行测试

记录日志

两个代理都包含全面的日志记录功能。通过以下方式设置日志级别：

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语音代理的一个示例实现提供。