agent-craft/m12_agents_sdk_swarm/README.md

🧩 模块说明：Agents SDK Swarm - 构建智能客服多智能体系统

📌 核心知识点：多智能体协作｜智能体转接机制｜工具调用｜MCP Server 集成｜流式响应输出

---

1. 模块概述

本模块基于 Agents SDK Swarm 框架实现了一个航空公司智能客服系统，展示了多智能体协作、智能转接和工具调用的核心功能。

• ✅ 掌握点：
  • 使用 Agents SDK 创建多个专业智能体（Agent）
  • 实现智能体之间的转接网络（Handoff Network）
  • 集成外部工具和 MCP Server（如高德地图服务）
  • 实现流式响应和实时交互
  • 配置动态提示词和上下文共享

---

2. tools.py （业务工具与上下文）

定义了系统使用的业务工具和全局上下文变量。

• ✅ 掌握点：

  • 使用 @function_tool 装饰器定义业务工具
  • 实现工具函数的逻辑
  • 配置全局上下文变量，实现智能体间信息共享

• 工具列表：

  • execute_refund()：执行退款逻辑
  • check_seat()：查询航班座位余量
  • context_variables：全局上下文，包含用户信息和航班信息

---

3. agent.py （智能体定义与配置）

定义了系统中的所有智能体及其交互规则。

• ✅ 掌握点：

  • 创建专业智能体（退票专员、改签专员、前台分诊员）
  • 配置智能体的指令和工具集
  • 集成高德地图 MCP Server
  • 建立智能体之间的转接网络
  • 使用动态提示词根据上下文生成指令

• 核心功能：

  • refund_agent：退票专员，处理退票请求
  • change_agent：改签专员，处理改签请求
  • triage_agent：前台分诊员，负责用户意图识别和智能转接
  • 建立了完整的智能体转接网络，支持灵活的任务流转

---

4. main.py （系统运行入口）

实现了智能客服系统的运行逻辑和用户交互界面。

• ✅ 掌握点：

  • 配置系统 tracing 选项
  • 连接 MCP Server
  • 实现流式响应处理
  • 管理对话历史和智能体状态
  • 处理各类事件（文本流、智能体切换、工具调用等）

• 技术特点：

  • 支持异步事件处理
  • 实时展示智能体切换和工具调用过程
  • 默认关闭 ChatGPT 的 Tracing 功能（可配置启用）

---

🔔 配置与运行说明

1. 环境配置：

   • 在项目根目录的 .env 文件中配置高德地图 API Key（必填）：

     AMAP_MAPS_API_KEY=your_amap_api_key
     

   • ChatGPT API Key 为选配（用于启用 Tracing）：

     OPENAI_API_KEY=your_openai_api_key
     

2. 运行方式：

   python -m m12_agents_sdk_swarm.main
   

3. 使用示例：

   ✈️ 客服系统启动...
   ✅ MCP Server (amap) connected.
   
   User: 我想退票
   🤖 [TriageAgent] 我帮您转接到退票专员
   🔀 [系统]: TriageAgent → RefundAgent
   🔧 [工具]: execute_refund
   ✅ [结果]: ✅️ 退款申请已提交，预计3个工作日内到账。
   🤖 [RefundAgent] 退款申请已提交，预计3个工作日内到账。您还需要其他帮助吗？
   

---

💡 扩展建议

• 尝试添加更多专业智能体，如值机专员、行李查询专员等
• 集成更多外部服务，如航班查询 API、支付系统等
• 优化智能体的转接逻辑，添加更复杂的意图识别规则

---

📋 注意事项

• 确保已正确安装所有依赖（可通过项目根目录的 requirements.txt 安装）
• 高德地图 API Key 是系统正常运行的必要条件
• 如遇到连接问题，检查网络设置和 API Key 的有效性
• 系统默认关闭 Tracing 功能，如需启用请在 main.py 中取消注释相关代码并配置 API Key