Luna: Voice-Enabled Expense Management Agent

Luna：语音启用的费用管理 Agent

Luna 是一个使用 Langgraph 构建的语音启用 AI 助手，帮助用户通过自然对话管理其费用。该项目演示了如何为任何 Langgraph Agent 创建语音界面，将语音转文本和文本转语音功能与强大的 Agent 框架相结合。

🌟 功能

• 语音交互：与 Luna 交谈并通过高质量文本转语音听取回复
• 费用管理：通过自然对话创建、查询、更新和删除费用
• 分类分类：根据描述自动对费用进行分类
• 数据库集成：将费用数据存储在 PostgreSQL 数据库中（通过 Supabase）
• 工具使用 Agent：使用 Langgraph 的 Agent 框架进行复杂推理

🛠️ 技术栈

后端

• Python 3.13：后端核心语言
• Langgraph：用于构建对话 AI 的 Agent 框架
• OpenAI：
  • Whisper API 用于语音转文本
  • GPT-4 Mini 用于 Agent 的推理
  • TTS API 用于文本转语音回复
• MCP（Model Calling Protocol）：用于定义和使用工具
• SQLAlchemy：用于数据库交互的 ORM
• Supabase：PostgreSQL 数据库提供商

音频处理

• sounddevice：用于从麦克风捕获音频
• scipy：用于音频文件处理

📋 前置要求

• Python 3.13
• OpenAI API 密钥
• Supabase 账户和数据库
• 麦克风和扬声器

🚀 快速开始

1. 克隆仓库

git clone https://github.com/rosiefaulkner/langgraph-voice-agent.git
cd langgraph-voice-agent

2. 设置虚拟环境并安装依赖

（推荐）使用 uv 进行依赖管理

在项目目录中设置 venv 并用一条命令安装所有依赖。

uv sync

3. 设置环境变量

在根目录中创建 .env 文件，包含以下变量：

OPENAI_API_KEY=your_openai_api_key
SUPABASE_URI=postgresql://postgres:[email protected]:5432/postgres

4. 运行应用程序

python main.py

🎤 使用 Luna

1. 运行应用程序
2. 出现提示时，说出你的请求（例如，"Create a new expense for lunch today that cost $15"）
3. 按 Enter 停止录音
4. Luna 将处理你的请求，在需要时与数据库交互，并通过语音进行回复
5. 继续对话或说"exit"或"quit"以结束会话

🧩 项目结构

langgraph-voice-agent/
├── main.py                  # Main application entry point
├── assistant_graph.py       # Langgraph agent definition
├── state.py                 # State management for the agent
├── voice_utils.py           # Audio recording and playback utilities
├── mcps/                    # Model Calling Protocol servers
│   ├── mcp_config.json      # MCP server configuration
│   └── local_servers/
│       └── db.py            # Database tools implementation
├── .env                     # Environment variables (not in repo)
├── .env.example             # Example environment variables
└── pyproject.toml           # Project dependencies

🔧 自定义 Agent

修改系统提示词

要更改 Luna 的个性或功能，编辑 assistant_graph.py 中的 system_prompt：

system_prompt = """You are Luna, the company's expense manager...

添加新工具

1. 创建新的 MCP 服务或将工具添加到 mcps/local_servers/ 中的现有服务
2. 在 mcps/mcp_config.json 中注册服务
3. 工具将自动对 Agent 可用

更改语音设置

修改 voice_utils.py 中的 TTS 设置：

async def play_audio(message: str):
    # ...
    async with openai_async.audio.speech.with_streaming_response.create(
        model="gpt-4o-mini-tts",
        voice="fable",  # Change the voice here
        input=cleaned_message,
        instructions="Speak in a cheerful, helpful tone with a brisk pace.",  # Modify instructions
        response_format="pcm",
        speed=1.2,  # Adjust speed
    ) as response:
        # ...

📚 资源

• Langgraph 文档
• OpenAI API 文档
• Model Context Protocol (MCP)
• SQLAlchemy 文档

🤝 贡献

欢迎贡献！请随时提交 Pull Request。