微信扫一扫README
🚀 巴西连锁超市智能客服系统 - Mercadinho Mercantes
本项目是为巴西连锁超市 Mercadinho Mercantes 打造的一套复杂的多智能体 AI 系统。该系统通过多个专业的 AI 智能体，为客户提供智能客服服务，能够处理产品咨询、销售协助、客户管理以及门店运营等工作。
🚀 快速开始
前提条件
- Python 3.8 或更高版本
- OpenAI API 密钥
- Git
安装步骤
-
克隆仓库
git clone <repository-url> cd mcp_mercadinho -
安装依赖项
pip install -r requirements.txt -
设置环境变量
export OPENAI_API_KEY="your_openai_api_key_here"或者创建一个
.env文件：echo "OPENAI_API_KEY=your_openai_api_key_here" > .env
运行应用程序
-
启动 MCP 服务器（在一个终端中）：
mcp run server.py --transport sse -
启动 Streamlit 客户端（在另一个终端中）：
streamlit run chat_multi_agent_client.py -
打开浏览器，并导航到 Streamlit 输出中显示的 URL（通常是
http://localhost:8501）
✨ 主要特性
🤖 多智能体架构
- 接待智能体：欢迎客户，并将他们引导至合适的服务。
- 销售智能体：处理产品咨询、推荐和销售协助。
- 客户维护智能体：管理现有客户账户和特殊折扣。
🛍️ 核心功能
- 产品目录：浏览带有价格和库存信息的可用产品。
- 门店信息：查找门店位置和联系方式。
- 促销系统：获取特定门店的促销活动和折扣信息。
- 客户管理：跟踪客户档案和忠诚度福利。
- 预约安排：预订门店参观和产品预订。
- 特殊折扣：为注册客户提供独家优惠。
🛠️ 技术特性
- MCP 集成：用于工具调用的模型上下文协议。
- Streamlit UI：现代、响应式的 Web 界面。
- 实时聊天：与 AI 智能体进行交互式对话。
- 工具可视化：透明查看 AI 工具的使用情况。
- 会话管理：持久的对话历史记录。
🏪 关于 Mercadinho Mercantes
Mercadinho Mercantes 是一家自豪的巴西零售公司，在圣保罗和里约热内卢拥有多家门店。我们的 AI 客服系统通过提供个性化的产品推荐、促销信息和无缝的预约安排，提升了客户体验。
🏗️ 架构
系统组件
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Streamlit UI │◄──►│ Multi-Agent │◄──►│ MCP Server │
│ (Frontend) │ │ System │ │ (Backend) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌──────────────────┐
│ OpenAI GPT-4 │
│ (LLM Backend) │
└──────────────────┘
智能体角色
接待智能体 (RecepcaoAssistente)
- 目的：与客户进行初始接触并进行路由。
- 职责：
- 欢迎客户光临 Mercadinho Mercantes。
- 展示公司信息和网站。
- 将客户引导至合适的专业智能体。
- 处理一般咨询。
销售智能体 (VendasAssistente)
- 目的：产品销售和推荐。
- 职责：
- 展示可用产品和库存。
- 提供产品推荐。
- 处理促销优惠。
- 安排门店参观。
- 处理销售咨询。
客户维护智能体 (ManutencaoSocioAssistente)
- 目的：现有客户支持和忠诚度管理。
- 职责：
- 验证客户会员状态。
- 为会员应用特殊折扣。
- 处理产品预订。
- 管理客户账户。
可用工具（MCP 函数）
| 工具 | 描述 | 参数 |
|------|-------------|------------|
| get_produtos_disponiveis() | 检索可用产品 | 无 |
| get_lojas() | 获取门店位置和信息 | 无 |
| get_promocao_por_loja(id_loja) | 获取特定门店的促销活动 | id_loja: int |
| get_info_cliente(nome) | 获取客户信息 | nome: str |
| reservar_pedido_com_desconto() | 预订带折扣的订单 | id_loja, id_cliente, data_hora |
| agenda_visita_para_compra() | 安排门店参观 | id_loja, data_hora |
📊 数据结构
产品
- 类别：果蔬、电子产品
- 信息：ID、名称、类别、价格、数量
- 示例：香蕉、苹果、PlayStation 5、LED 电视
门店
- 位置：圣保罗（帕雷赫罗斯、穆卡）、瓜鲁雅、圣安德烈、里约热内卢（伊帕内玛、新伊瓜苏）
- 信息：ID、名称、城市、州
客户
- 类型：普通客户、会员（享受特殊折扣）
- 信息：ID、姓名、关联门店、折扣资格
💻 使用示例
产品咨询
用户: "你们有哪些产品可供选择？"
智能体: [展示带有价格和库存信息的产品目录]
门店参观预约
用户: "我想参观一家门店看看 PlayStation 5"
智能体: [找到最近的门店，查看促销活动，安排参观]
客户折扣查询
用户: "我叫约翰·列侬，我有什么特殊折扣吗？"
智能体: [验证会员身份，应用特殊定价]
🔧 配置
环境变量
OPENAI_API_KEY：用于访问 GPT - 4 的 OpenAI API 密钥
模型设置
- 模型：GPT - 4 - 1106 - preview
- 温度：0（确定性响应）
- 工具选择：自动
- 并行工具调用：禁用
🛡️ 安全注意事项
⚠️ 重要提示
- API 密钥应安全存储在环境变量中。
- 切勿将 API 密钥提交到版本控制系统。
- 在本地开发时使用
.env文件。- 在生产环境中考虑实施速率限制。
🤝 贡献指南
- 分叉仓库
- 创建一个功能分支 (
git checkout -b feature/amazing-feature) - 提交你的更改 (
git commit -m 'Add amazing feature') - 推送到该分支 (
git push origin feature/amazing-feature) - 打开一个拉取请求
📄 许可证
本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。
🆘 支持
如需支持和提问：
- 查看 问题 页面
- 联系开发团队
- 访问 Mercadinho Mercantes
🔮 未来改进
- [ ] 与真实库存系统集成
- [ ] 支持支付处理功能
- [ ] 支持多语言（葡萄牙语/英语）
- [ ] 开发移动应用程序
- [ ] 高级分析和报告
- [ ] 与 CRM 系统集成
为 Mercadinho Mercantes 用心打造 ❤️