AI导哈

多智能体客户服务系统

一个基于Google Agent Development Kit (ADK)和Model Context Protocol (MCP)构建的生产级多智能体客户服务系统，具备高级智能体间通信、工具集成和智能路由功能。

  • by YeochanY
  • Jupyter Notebook
  • 本地部署
  • 更新于
在 GitHub 查看 YeochanY/Multi-Agent-Customer-Service-System-with-A2A-and-MCP

使用说明

集成MCP的多Agent客户服务系统

一个生产就绪的多代理客户服务系统，使用谷歌的代理开发工具包（ADK）和模型上下文协议（MCP）构建。该系统演示了高级代理到代理（A2A）通信、工具集成和客户支持工作流的智能路由。

🌟 特性

  • 多代理架构：路由器、客户数据代理和支持代理协同工作
  • MCP协议集成：客户数据库操作的标准化工具访问
  • 代理间通信：专业代理之间的无缝协调
  • 实时工具执行：通过MCP服务器直接进行数据库操作
  • 全面的客户管理：CRUD操作、票证创建和历史跟踪
  • 生产准备就绪：内置错误处理、日志记录和可观察性

🏗️ 建筑

┌─────────────────┐
│  Router Agent   │  ← Orchestrates all incoming requests
└────────┬────────┘
         │
    ┌────┴────┐
    ↓         ↓
┌─────────┐ ┌─────────┐
│Customer │ │Support  │  ← Specialized agents
│Data     │ │Agent    │
│Agent    │ │         │
└────┬────┘ └─────────┘
     │
     ↓
┌─────────────────┐
│  MCP Server     │  ← Tool provider
│  (Flask + SSE)  │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  SQLite DB      │  ← Data storage
│  (Customers +   │
│   Tickets)      │
└─────────────────┘

🚀 快速开始

先决条件

  • Python 3.10+
  • Gemini模型的Google API密钥
  • ngrok authtoken（可选，用于公共访问）

安装

  1. 克隆仓库
git clone <repository-url>
cd customer-service-mcp
  1. 安装依赖项
pip install google-adk google-generativeai flask flask-cors pyngrok termcolor
  1. 设置环境变量
# Set your API keys
os.environ['GOOGLE_API_KEY'] = 'your-google-api-key'
os.environ['NGROK_AUTHTOKEN'] = 'your-ngrok-token'  # Optional

运行系统

步骤1：启动MCP服务器

跑吧 mcp_server.ipynb 笔记本：

# This will:
# 1. Initialize the SQLite database
# 2. Start the Flask MCP server
# 3. Expose it via ngrok (optional)
# 4. Display the server URL

输出：

✅ MCP Server is running!
🔗 Local URL: http://127.0.0.1:5000
🌍 Public URL: https://your-app.ngrok-free.dev
🔍 MCP Endpoint: https://your-app.ngrok-free.dev/mcp

步骤2：启动代理系统

跑吧 a2a_team.ipynb 笔记本：

# Configure the MCP server URL
MCP_SERVER_URL = "http://127.0.0.1:5000/mcp"

# Agents are automatically initialized
# Start querying!
await ask_agent_team("Get customer information for ID 5")

🤖 代理能力

路由器代理（编排器）

  • 分析用户意图
  • 将请求发送给适当的专业代理
  • 综合最终响应
  • 处理澄清

技能：

  • 客户查询编排
  • 多步骤工作流管理
  • 意图分类

客户数据代理（专家）

  • 通过MCP工具直接访问客户数据库
  • 处理所有数据操作

技能：

  • retrieve_customer：按ID或筛选器获取客户记录
  • update_customer：通过验证修改客户信息
  • validate_customer_input：更新前验证字段

可用的MCP工具：

  • get_customer(customer_id)：检索特定客户
  • list_customers(status?)：列出所有/筛选的客户
  • update_customer(customer_id, name?, email?, phone?)：更新记录
  • create_ticket(customer_id, issue, priority)：创建支持票
  • get_customer_history(customer_id)：获取门票历史记录

支持代理（专家）

  • 处理一般客户支持查询
  • 提供故障排除和指导
  • 升级复杂问题

技能：

  • handle_support_query：回答支持问题
  • request_customer_context：从客户数据代理获取数据
  • escalate_issue：通往合适团队的路线
  • provide_recommendation：建议解决方案

📝 示例用法

示例1：数据检索

await ask_agent_team("Get customer information for ID 5")

答复：

Here is the information for customer ID 5:

**Name:** Charlie Brown
**Email:** charlie.brown@email.com
**Phone:** +1-555-0105
**Status:** active
**Created At:** 2025-11-27 23:12:44
**Updated At:** 2025-11-27 23:12:44

示例2：支持查询

await ask_agent_team("I'm customer 12345 and need help upgrading my account")

代理流程：

  1. 路由器→ 客户数据代理（验证客户）
  2. 客户数据代理→ 支持代理（处理升级）
  3. 支援谍员→ 路由器→ 用户（提供指导）

示例3：复杂工作流

await ask_agent_team("I've been charged twice, please refund immediately!")

答复：

{
  "response": "I understand your concern about being double-charged and the urgency of a refund. 
              I'll need to access your account details to investigate this issue thoroughly 
              and process your request. Please bear with me while I look into this for you."
}

🔍 MCP协议详细信息

协议版本

  • MCP版本: 2024-11-05
  • 运输：服务器通过HTTP发送事件（SSE）
  • 消息格式：JSON-RPC 2.0

可用的MCP工具

工具 说明 参数
get_customer 按ID检索客户 customer_id: int
list_customers 列出所有/筛选的客户 status?: "active" | "disabled"
update_customer 更新客户信息 customer_id: int, name?: str, email?: str, phone?: str
create_ticket 创建支持票 customer_id: int, issue: str, priority: str
get_customer_history 获取门票历史记录 customer_id: int

MCP服务器端点

  • MCP端点: POST /mcp -主要协议端点
  • 健康检查: GET /health -服务器状态
  • 协议：基于SSE的JSON-RPC 2.0

📊 事件跟踪示例

📡 FULL AGENT EVENT TRACE
──────────────────────────────────────────────────────────

[Event 1]
  author       : router_agent
  model_version: gemini-2.5-flash
  🛠 Function Call (part 1)
     name : transfer_to_agent
     args : {"agent_name": "customer_data_agent"}

[Event 2]
  author       : router_agent
  🔀 transfer_to_agent
     router_agent → customer_data_agent

[Event 3]
  author       : customer_data_agent
  🛠 Function Call (part 1)
     name : get_customer
     args : {"customer_id": 5}

[Event 4]
  📦 Function Response (part 1)
     from : get_customer
     response : {"success": true, "customer": {...}}

🛠️ 技术实现

代理卡（A2A协议）

每个代理都会公开一张代理卡，其中包含：

  • 能力：流媒体支持，输入/输出模式
  • 技能：详细的技能描述和示例
  • 运输：JSON-RPC首选协议
  • 版本：语义版本控制

关键技术

  • 谷歌ADK：代理编排和管理
  • 双子座2.5闪光灯：代理推理法学硕士
  • 烧瓶：MCP服务器实现
  • SQLite：客户数据存储
  • 吸烟：公共隧道（可选）
  • 上海证券交易所：实时事件流

📈 学习与挑战

关键收获

  1. A2A通信：对多智能体系统中的结构化消息传递、基于工具的操作和状态管理有了深入的理解

  2. MCP协议：了解了MCP如何实现标准化工具集成，以及代理如何通过外部数据源进行协调

  3. 代理商专业化：发现了明确角色分离的重要性以及专业代理如何提高系统可靠性

克服挑战

  1. 协调失败：跨路由器、专家和MCP调试错误需要全面的事件记录和消息跟踪

  2. 状态管理：确保跨代理传输的状态一致需要仔细设计上下文传递

  3. 工具集成：将MCP工具响应映射到代理操作需要稳健的错误处理和验证

  4. 可观测性：实施了详细的事件跟踪，以了解多步骤工作流程和代理决策

🔐 最佳实践

  1. 错误处理：所有MCP操作都包含在try-catch块中
  2. 验证：数据库操作前的输入验证
  3. 日志记录：用于调试的全面事件日志记录
  4. 状态管理：代理之间传递清晰的上下文
  5. 工具设计：定义良好的工具模式和描述

相关 MCP