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

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

---

## 模块概述

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

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

---

### 1. `s01_tools.py` （业务工具与上下文）

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

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

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

---

### 2. `s02_agent.py` （智能体定义与配置）

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

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

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

---

### 3. `s03_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. **运行方式**：
   ```bash
   python -m m12_agents_sdk_swarm.s03_main
   ```

3. **使用示例**：
   ```
   ✈️ 客服系统启动...
   ✅ MCP Server (amap) connected.

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

---

### 💡 扩展建议

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

---

### 📋 注意事项

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