---
created: "2026-03-29"
type: project
status: 未开始
parent: "[[Smart Support]]"
phase: 2
timeline: "第 3-4 周"
---

# Phase 2：多 Agent + 安全

## 目标

让 Supervisor 具备真正的多 Agent 路由能力，能根据用户意图选择正确的 Agent。同时完善安全机制：中断超时处理、Webhook 升级通知。这个阶段结束时，系统能处理多种类型的客服请求，并在无法解决时通过 Webhook 通知人工。

## 前置条件

- [[Smart Support/Phase 1 - 核心框架]] 完成
- 核心聊天闭环端到端可用
- PostgresSaver + interrupt() 基础流程工作正常

## 阶段产出

- Supervisor 能准确路由不同类型的请求到对应 Agent
- 多意图请求（「取消订单并给我折扣」）能被拆分并按序处理
- 无法解决的问题通过 Webhook 通知人工客服
- 过期中断自动取消并提供重试选项
- 2-3 个垂直行业模板开箱可用

## 集成检查点

第 4 周末验证：
1. 发送订单查询 → 路由到 order_lookup agent
2. 发送「取消订单并退款」→ 按序处理两个操作
3. 发送无法处理的请求 → Webhook POST 发出
4. 触发确认 → 30 分钟不操作 → 自动取消 → 重新发消息收到重试提示
5. 加载电商模板 YAML → 相关 agents 自动注册

---

## 任务清单

### 1. 完善 Supervisor 路由

- [ ] 优化 supervisor 的 agent 描述，使路由更准确
- [ ] 多意图处理：supervisor 识别复合请求，拆分为多个子任务，按序执行
  - 例如「取消订单 1042 并给我一个 10% 折扣码」→ 先路由到 order_actions（取消），再路由到 discount（发码）
- [ ] 模糊/冲突意图处理：supervisor 无法判断时，返回澄清问题（「您是想查询订单还是取消订单？」）
- [ ] 路由失败日志：每次路由记录 `{intent, selected_agent, confidence}`，为后续评估提供数据

### 2. 过期中断处理

- [ ] 中断触发时记录 `interrupt_timestamp` 到 graph state
- [ ] 用户恢复对话时检查：`current_time - interrupt_timestamp > 30 min`
- [ ] 超时行为：
  1. 将该操作标记为已取消（不执行）
  2. 返回消息：「您之前请求的[操作描述]已因超时取消。订单状态可能已变化，需要我重新查看吗？」
  3. Agent 重新评估当前状态（重新调用查询工具），而不是直接重试旧操作
- [ ] 未超时：正常恢复 interrupt 流程（approve/reject）

### 3. Webhook 升级通知

- [ ] 配置项：`webhook_url`（在 agents.yaml 或环境变量中配置）
- [ ] 触发条件：
  - Agent 明确表示无法处理（返回 escalation 标记）
  - Supervisor 连续 3 次路由失败（用户重复同一问题）
  - 用户主动请求人工客服
- [ ] Webhook payload 格式：

```json
{
  "event": "escalation",
  "thread_id": "uuid",
  "timestamp": "2026-04-10T14:30:00Z",
  "reason": "agent_unable_to_resolve",
  "conversation_summary": "客户询问关于批量退货的问题，order_lookup agent 无法找到相关功能",
  "messages": [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "customer_context": {
    "resolved_entities": {"order_id": "1042"}
  }
}
```

- [ ] HTTP POST 发送，设置 10 秒 timeout
- [ ] 失败重试：最多 3 次，指数退避（1s, 2s, 4s）
- [ ] 重试全部失败 → 记录日志（ERROR 级别），不阻塞聊天流程
- [ ] 在聊天 UI 中通知用户：「已通知人工客服，他们会尽快联系您」

### 4. 垂直行业模板

- [ ] 创建模板目录 `backend/templates/`
- [ ] 电商模板 `ecommerce.yaml`：

```yaml
name: ecommerce
description: 电商客服模板 - 订单管理、物流查询、退换货
agents:
  - name: order_lookup
    description: 查询订单状态、物流跟踪、收货确认
    permission: read
    personality:
      tone: professional
      greeting: "您好！我可以帮您查询订单相关信息。"
    tools: [get_order, get_tracking, list_orders]

  - name: order_actions
    description: 取消订单、修改地址、申请退换货
    permission: write
    personality:
      tone: careful
      greeting: "我可以帮您处理订单变更，所有操作都会先确认。"
    tools: [cancel_order, modify_address, request_return]

  - name: promotions
    description: 查询优惠活动、发放折扣码
    permission: write
    personality:
      tone: enthusiastic
    tools: [apply_discount, check_promotions]
```

- [ ] SaaS 模板 `saas.yaml`：账号管理、订阅变更、功能咨询
- [ ] 金融科技模板 `fintech.yaml`：账户查询、交易记录、转账操作
- [ ] 模板加载机制：启动时指定 `--template ecommerce` 或在配置中设置 `template: ecommerce`
- [ ] 模板与自定义 agents.yaml 合并：模板提供默认值，自定义配置覆盖

### 5. 新增演示 Agent

在 Phase 1 的基础上增加写操作 Agent：

- [ ] `order_actions` agent：取消订单（`cancel_order`）、修改地址（`modify_address`）
- [ ] `discount` agent：发放优惠券（`apply_discount`）、生成折扣码（`generate_coupon`）
- [ ] 所有写操作工具标记 `permission: write` → 自动触发 interrupt

### 6. 测试

- [ ] **路由测试：** 「查询订单」→ order_lookup，「取消订单」→ order_actions，「给我折扣」→ discount
- [ ] **路由测试：** 模糊请求 → 返回澄清问题
- [ ] **多意图测试：** 「取消订单并退款」→ 按序执行两个操作
- [ ] **超时测试：** interrupt 后 mock 时间超过 30 分钟 → 自动取消 + 重试提示
- [ ] **超时测试：** interrupt 后 mock 时间未超过 30 分钟 → 正常 approve/reject
- [ ] **Webhook 测试：** 升级触发 → HTTP POST 发出，payload 格式正确
- [ ] **Webhook 测试：** 目标 URL 不可达 → 重试 3 次 → 记录日志 → 聊天不中断
- [ ] **模板测试：** 加载电商模板 → agents 正确注册
- [ ] **模板测试：** 自定义配置覆盖模板默认值
- [ ] **E2E 测试：** 完整升级流程（无法处理 → webhook 发出 → 用户收到通知）

## 技术要点

| 功能 | 实现方式 |
|------|---------|
| 多意图拆分 | Supervisor LLM 识别并按序调度 |
| 超时检测 | graph state 记录 timestamp，resume 时比较 |
| Webhook | httpx.AsyncClient POST，asyncio 重试 |
| 模板加载 | PyYAML 加载 + 与自定义 YAML 深度合并 |

## 风险与缓解

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 多意图拆分不准确 | 操作顺序错误或遗漏 | 先处理常见组合，复杂情况要求用户分步操作 |
| Webhook 目标服务不稳定 | 升级通知丢失 | 重试 + 日志 + 聊天内告知用户 |
| 超时时间 30 分钟不合适 | 过早或过晚取消 | 配置化，允许每个 agent 自定义 TTL |

## Related

- [[Smart Support/Phase 1 - 核心框架]]
- [[Smart Support/Phase 3 - OpenAPI 自动发现]]
- [[Smart Support]]