184 lines
7.0 KiB
Markdown
184 lines
7.0 KiB
Markdown
---
|
||
created: 2026-03-29
|
||
type: project
|
||
status: 未开始
|
||
parent: "[[Smart Support]]"
|
||
phase: 2
|
||
timeline: 第 3-4 周
|
||
tags:
|
||
- phase-2
|
||
- multi-agent
|
||
- agent-orchestration
|
||
- intent-routing
|
||
- webhook
|
||
- escalation
|
||
- interrupt
|
||
- ttl-timeout
|
||
- industry-template
|
||
- security
|
||
---
|
||
|
||
# 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]]
|