Multiagent Customer Support

多代理客户支持系统

MCP供电•谷歌Gemini 2.0 Flash Lite•A2A协议•SQLite接地

该项目实现了一个功能齐全的 多代理客户支持平台 为芝加哥大学的应用生成人工智能课程而建。\ 它结合了 LLM推理, 数据库支持的工具, 主控程序, LangGraph风格编排，以及 多模式界面 （文本+语音）。

______________________________________________________________________

项目概述

该系统模拟了智能客户支持工作流程。三个核心代理合作：

• 理解用户意图
• 检索客户详细信息
• 解决多步骤查询
• 创建或更新支持票
• 提供有用的自然语言响应
• 通过CLI、Streamlit Web UI或语音到语音界面进行交互

管道是 基于真实的SQLite数据库 通过MCP服务器（FastMCP），并由 自定义路由器代理 灵感来自LangGraph。

______________________________________________________________________

项目结构

MULTIAGENT-CUSTOMER-SUPPORT/
├── agents/                 # Multi-agent logic
│   ├── a2a_server.py       # Agent-to-Agent HTTP server
│   ├── data_agent.py       # MCP HTTP client
│   ├── router_agent.py     # LangGraph-style orchestrator
│   └── support_agent.py    # GPT-4o-mini reasoning
│
├── demo/                   # Test scenarios and demos
│   ├── demo.py             # Main demo script
│   └── demo1.py            # Alternative demo
│
├── extras/                 # Optional UI components
│   ├── chat_cli.py         # CLI demo 
│   ├── streamlit_app.py    # Web UI
│   ├── voice_chat.py       # Speech-to-speech assistant
│   └── server.py           # Additional server utilities
│
├── mcp_impl/               # MCP protocol implementation
│   ├── mcp_client.py       # MCP HTTP client
│   ├── mcp_server.py       # MCP HTTP server (FastAPI)
│   └── mcp_tools.py        # MCP tool definitions
│
├── src/                    # Database and setup
│   ├── database_setup.py   # SQLite database initialization
│   ├── support.db          # SQLite database file
│   └── setup.py            # Setup utilities
│
├── README.md
├── requirements.txt
├── quick_start.sh          # Quick start script
└── .gitignore

______________________________________________________________________

系统架构

flowchart TD

    UI[User Interfaces
CLI • Streamlit • Voice] --> Router

    Router[Router Agent
Orchestrator
Port 10020] --> SupportAgent
    Router --> DataAgent
    Router --> TicketNode

    SupportAgent[Support Agent
Gemini 2.0 Flash Lite
Port 10022
Reasoning + Action Planning]

    DataAgent[Data Agent
MCP HTTP Client
Port 10021
DB Tools: get/update/list]

    TicketNode[Ticket Creation Node
create_ticket]

    DataAgent -->|HTTP| MCPServer
    TicketNode -->|HTTP| MCPServer

    MCPServer[MCP HTTP Server
FastAPI
Port 8001
SQLite: src/support.db]

    A2A[A2A Server
Agent-to-Agent Protocol
Exposes agents as HTTP services]
    
    Router -.->|Optional| A2A
    DataAgent -.->|Optional| A2A
    SupportAgent -.->|Optional| A2A

______________________________________________________________________

特性

支持代理（Gemini 2.0 Flash Lite）

• 意图分类
• 多意图检测
• 行动计划（响应、请求数据、创建票）
• 用于路由的结构化JSON输出

数据代理（MCP HTTP客户端）

• 用途 McpToolset 和 StreamableHTTPConnectionParams 用于自动工具发现
• 自动从服务器发现和处理MCP工具：

- get_customer - list_customers - update_customer - get_customer_history - create_ticket

• 不需要手动工具定义-工具是动态发现的

MCP服务器（FastAPI+SQLite）

• MCP协议的HTTP/SSE传输
• 持久SQLite存储(src/support.db)
• 数据库支持的工具功能
• LLM的确定性基础
• 与MCP检查器兼容

A2A服务器（代理到代理协议）

• 将代理暴露为独立的HTTP服务：

- 路由器代理（端口10020） - 数据代理（端口10021） - 支持代理（端口10022）

• 每个代理暴露：

- /.well-known/agent-card.json -A2A元数据 - /process -主查询端点 - /health -健康检查端点

路由器代理（LangGraph风格）

• 多步推理
• 基于节点的路由
• 条件驱动的转变
• 最终反应综合

用户界面

• CLI聊天
• 自动化硬件场景运行器
• 流线型web UI
• 完整的语音交互（Whisper+TTS）

______________________________________________________________________

安装

1.克隆仓库

git clone https://github.com/XuYunlei/multiagent-customer-support.git
cd multiagent-customer-support

2.创造环境

conda create -n mcp python=3.10 -y
conda activate mcp

3.安装依赖项

pip install -r requirements.txt

注： 对于语音功能，您可能还需要：

# macOS
brew install ffmpeg

# Linux
sudo apt-get install ffmpeg

4.设置环境变量

创建一个 .env 项目根目录中的文件：

echo 'GOOGLE_API_KEY=your-google-api-key-here' > .env
echo 'OPENAI_API_KEY=sk-proj-your-key-here' >> .env  # Optional: for voice features

注： GOOGLE_API_KEY 双子座特工需要。 OPENAI_API_KEY 仅在使用语音功能（Whisper/TTS）时才需要。

5.初始化数据库

python src/database_setup.py

______________________________________________________________________

如何跑步

🚀 快速入门（推荐）

最简单的入门方法是使用快速入门脚本：

chmod +x quick_start.sh
./quick_start.sh

此脚本将：

1. 检查 .env 文件
2. 如果需要，初始化数据库
3. 启动MCP服务器（端口8001）
4. 启动A2A服务器（端口10020-10022）
5. 运行演示脚本

注： 演示包括查询之间的10秒延迟，以避免达到自由层API配额限制。

🔹 手动设置

步骤1：启动MCP服务器

python mcp_impl/mcp_server.py

MCP服务器将在 http://localhost:8001

步骤2：（可选）启动A2A服务器

python agents/a2a_server.py

这将代理暴露为端口10020-10022上的HTTP服务

步骤3：运行演示

python demo/demo.py

🔹 其他接口

交互式CLI聊天

python extras/chat_cli.py

流媒体Web应用程序

streamlit run extras/streamlit_app.py

语音助理

python extras/voice_chat.py

______________________________________________________________________

端到端演示（A2A协调）

以下是运行的输出 python demo/demo1.py （任务测试场景）：

所有五个场景都展示了多步代理之间的协调 路由器代理, 支持代理（Gemini 2.0 Flash Lite），以及 数据代理（MCP） 通过MCP HTTP服务器使用真实的数据库接地。

______________________________________________________________________

⭐ 场景1——简单查询

用户： *“获取ID 1的客户信息”*

Router → Data Agent: get_customer(1)
Data Agent → MCP Server: Database lookup
Final Answer → "OK. I have the customer information for John Doe: Customer ID: 1, Name: John Doe, Email: john.doe@example.com, Phone: +1-555-0101, Status: active"

______________________________________________________________________

⭐ 场景2——协同查询（任务分配）

用户： *“我是客户1，需要帮助升级我的帐户”*

Router → Data Agent: Get customer context
Router → Support Agent: Handle upgrade request
Support Agent → Data Agent: Create ticket via MCP
Data Agent → MCP Server: create_ticket(customer_id=1, issue="upgrading account", priority="high")
Final Answer → "OK. I have created a high-priority ticket (ID 39) for you regarding upgrading your account."

______________________________________________________________________

⭐ 场景3——复杂查询（协商）

用户： *“显示所有有未结门票的活跃客户”*

Router → Data Agent: Attempts complex aggregation
Data Agent → Router: Recognizes tool limitation
Agents negotiate → Provide alternative solution
Final Answer → "I am sorry, I cannot directly show you all active customers with open tickets. However, I can list all active customers and also retrieve the ticket history for individual customers if you provide their IDs."

______________________________________________________________________

⭐ 情景4——升级

用户： *“我已经被收费两次了，请立即退款！”*

Router → Detects urgency keywords
Router → Support Agent: Escalate billing issue
Support Agent → Recognizes high-priority scenario
Final Answer → "I understand you've been charged twice and need a refund immediately. Since this is a billing issue, I will create a high-priority ticket right away. However, I need your customer ID to proceed."

______________________________________________________________________

⭐ 场景5——多意图（多步协调）

用户： *“更新我的电子邮件至newemail@example.com并显示我的门票历史记录”*

Router → Data Agent: update_customer(customer_id=1, email="newemail@example.com")
Router → Data Agent: get_customer_history(customer_id=1)
Data Agent → MCP Server: Parallel tool execution
Final Answer → "Okay, I have updated the email for customer ID 1 to newemail@example.com. It seems there are no tickets associated with this customer."

______________________________________________________________________

✔ 总结

这些场景展示了所有必需的A2A协调模式：

• 任务分配 （场景2）：将路由器委托给专业代理
• 谈判 （场景3）：当直接解决方案不可用时，代理会进行协调
• 多步骤协调 （场景5）：并行工具执行与响应合成
• 工具接地：所有操作均使用MCP工具(get_customer, create_ticket, update_customer, get_customer_history)
• A2A协议：与代理卡的HTTP/JSON-RPC通信
• SQLite支持状态：数据库维护持久的客户和票证状态

______________________________________________________________________

交付物

端到端Python程序 （满足任务要求）：

• demo/demo1.py -包含所有5个必需查询的分配测试场景
• demo/demo.py -其他基本场景
• quick_start.sh -自动设置：启动服务器并运行演示

要运行：

./quick_start.sh
# Or manually: python mcp_impl/mcp_server.py & python agents/a2a_server.py & python demo/demo1.py

所有输出都在终端中捕获，显示A2A流、MCP工具调用和最终答案。

______________________________________________________________________

结论

在整个项目中，我对构建意味着什么有了更深入的理解 *真* 超越简单LLM提示的多代理系统。实现MCP服务器教会了我如何用可靠的、基于工具的数据访问来支持代理的推理。构建数据代理帮助我了解了如何异步构建工具调用，以及如何以安全和可重复的方式将LLM与真实数据库连接。使用结构化JSON输出设计Support Agent增强了我对受控推理、行动计划和多步骤工作流的理解。路由器代理是最具挑战性的部分，但它教会了我如何以反映真实LangGraph风格架构的方式编排多个代理之间的交互。这段经历使代理系统在概念上对我来说“点击”。

最大的挑战是调试异步MCP进程、管理多个环境以及连接音频I/O以进行语音交互。集成语音输入和TTS使我摆脱了简单的纯文本管道，并帮助我了解了多模式代理在实践中是如何构建的。我还面临着几个实际的工程挑战——导入路径问题、虚拟环境冲突，以及确保数据库在代理调用中正确持久——但克服这些挑战使我成为一个更加自信、足智多谋的工程师。总的来说，这个项目给了我构建一个完整的、生产风格的多代理架构的实践经验，并加强了我在工具基础、编排和系统级人工智能设计方面的技能。

______________________________________________________________________

技能展示

• 多智能体系统
• 模型上下文协议（MCP）-HTTP/SSE传输
• FastAPI服务器开发
• 代理对代理（A2A）协议
• Google Gemini 2.0 Flash Lite（通过Google ADK进行LLM推理）
• OpenAI Whisper（ASR）
• OpenAI TTS（语音生成）
• 异步Python（asyncio）
• SQLite数据库设计
• 工具接地LLM
• LangGraph风格编排
• 简化UI开发
• 音频处理（音响设备，pydub）
• 基于HTTP的代理通信

______________________________________________________________________

未来的增强功能

• 多回合会话记忆
• 客户和票务管理仪表板
• 与外部API集成
• RAG增强支持答案
• 支持多用户身份验证
• 持续的语音历史记录

______________________________________________________________________

致谢

课程： *应用生成人工智能和多模态智能*\ 芝加哥大学，2025