任务5——多代理客户服务系统（A2A+MCP）
该存储库包含使用Google的代理到代理（A2A）协议以及模型上下文协议（MCP）数据访问层的多代理客户服务系统的端到端实现。\ 所有组件——MCP工具、三个A2A代理、编排逻辑和完整的测试套件——都在笔记本中实现：
A5.ipynb这种设计保持了项目的自包含性和易于运行，同时仍然展示了任务所需的完整架构。
______________________________________________________________________
- 项目概述
______________________________________________________________________
该系统模拟了一个现实的客户服务工作流程，其中多个专业代理协作：
• 路由器代理\ 解释传入的用户请求，识别意图域，并决定应调用哪些下游代理。
• 客户数据代理\ 以独占方式连接到MCP服务器以检索或修改客户记录。处理结构化数据查询，如配置文件查找、客户列表、票务历史和字段更新。
• 客服专员\ 专注于与支持相关的任务，包括计费问题、退款检测、升级请求、工单创建和工单查询。
• MCP服务器（SQLite支持）\ 为数据库操作提供标准化的JSON-RPC风格工具： -get_客户\ -列表_客户\ -更新_客户\ -创建_票\ -get_customer_历史
这三个A2A代理在笔记本电脑内作为独立的HTTP服务运行，并通过JSON-RPC A2A消息传递进行通信。
______________________________________________________________________
- 系统架构
______________________________________________________________________
笔记本实现了以下组件：
- 数据库层\
启动时创建了一个轻量级的SQLite数据库。\ 表格包括：
- 客户（id、姓名、电子邮件、电话、状态、created_at、updated_at） - 票证（id、customer_id、问题、状态、优先级、创建at）
- MCP工具接口\
笔记本电脑定义了一个最小的类似MCP的服务器，提供了5个所需的工具。\ 代理商执行的所有客户和票务操作都必须使用这些工具；没有代理直接访问数据库。
- 三个A2A代理（路由器/数据/支持）\
每个代理都作为Starlette+A2aAgentExecutor服务在自己的端口上运行。\ 每个代理只生成结构化的JSON输出。
- 编排逻辑\
Router Agent分析输入文本并处理：
- 意图检测 - 路由规则 - 组合流程（客户背景+支持行动） - 顺序和并行协调 - 聚合来自多个代理的JSON响应
- 集成测试套件\
笔记本运行几个场景进行验证：
- 任务分配 - 升级和谈判 - 多步骤推理 - 复杂的跨代理工作流
______________________________________________________________________
- 安装和环境设置
______________________________________________________________________
克隆此存储库：
git clone
cd 创建并激活Python虚拟环境：
python -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows安装所需的依赖项：
pip install -r requirements.txt对于基于API的模型（Gemini），请设置您的环境密钥：
export GOOGLE_API_KEY=""
# or use Colab's userdata storage不需要额外的Python文件或文件夹——笔记本包含了整个实现。
______________________________________________________________________
- 运行系统
______________________________________________________________________
打开：
A5.ipynb然后从上到下执行所有单元格。
笔记本将自动：
•初始化SQLite数据库\ •启动MCP工具服务器\ •启动所有三个A2A代理服务器（在端口9300、9301、9400上）\ •打印每个代理的实时日志\ •运行所有端到端测试场景
所有服务都在后台线程内执行，以允许笔记本在测试期间发出A2A请求。
______________________________________________________________________
- 已实施的测试场景
______________________________________________________________________
笔记本演示了作业中所需的多种协调模式：
1） 简单查询
“获取ID 5的客户信息”\ → 路由到客户数据代理→ MCP查找
2） 协调请求
“我是客户12345，需要帮助升级我的帐户”\ → 客户数据代理（上下文）+支持代理（升级处理）
3） 多代理协商
“显示所有有未结门票的活跃客户”\ → Data Agent检索活跃客户→ 支持代理过滤票证状态
4） 升级/紧急检测
“我已经被收费两次了，请立即退款！”\ → 支持代理检测到账单+高优先级
5） 多意图命令
“将我的电子邮件更新到X并显示我的机票历史记录”\ → 路由器拆分请求→ 通过数据代理+历史检索进行更新
所有结果都通过Router Agent以结构化JSON的形式返回。
______________________________________________________________________
- 存储库内容
______________________________________________________________________
.gitignore#Python和笔记本忽略规则\ requirements.txt#MCP+A2A+SQLite的依赖关系\ A5.ipynb#完整实现（代理、MCP、测试）\ A5.html#笔记本的静态html导出（可选）
整个项目有意整合到一个笔记本中，以简化评估并降低环境复杂性。
______________________________________________________________________
- 故障排除
______________________________________________________________________
MCP服务器无法访问
- 重新启动笔记本内核
- 确保端口8000空闲
代理没有响应
- 验证代理启动日志
- 确认端口9300/9301/9400未被阻塞
数据库问题
- 删除生成的
mcp.db文件并重新运行安装单元
执行缓慢
- A2A调用涉及多个HTTP往返；每次测试允许1-3秒
- 如果端口未完全初始化，请重新运行测试套件
______________________________________________________________________
- 任务要求检查表
______________________________________________________________________
✔ 实现了三个代理架构（路由器/客户数据/支持）\ ✔ MCP与所有五个必需工具的集成\ ✔ 使用JSON-RPC的A2A通信\ ✔ 任务分配场景\ ✔ 谈判/升级场景\ ✔ 多步骤协调场景\ ✔ 具有正确模式的SQLite数据库\ ✔ 端到端演示笔记本\ ✔ 仅限结构化JSON输出\ ✔ 代理间交互的日志记录\ ✔ 结论和文件包括
______________________________________________________________________
- 结论
______________________________________________________________________
该项目展示了多智能体系统如何通过A2A和MCP等标准化协议进行协调。\ 构建路由器、客户数据代理和支持代理需要明确的意图检测、结构化的消息传递和精心排序的工具调用。组合工作流显示了独立服务如何协作可靠地完成复杂任务。
该实现还突出了实际的工程挑战，如端口管理、工具错误处理和多步推理，并说明了如何设计通过定义良好的接口交换信息的模块化代理。
______________________________________________________________________
- 许可证
______________________________________________________________________
该知识库作为应用生成人工智能代理和多模式智能课程的一部分用于学术用途。