kai/knowledge-base

Fork 0

Files

Yaojia Wang 0c53be0f17 Add tags

2026-03-30 15:14:26 +02:00

7.0 KiB

Raw Blame History

created, type, status, parent, phase, timeline, tags

created

type

status

parent

phase

timeline

Phase 2：多 Agent + 安全

目标

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

前置条件

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

阶段产出

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

集成检查点

第 4 周末验证：

发送订单查询 → 路由到 order_lookup agent
发送「取消订单并退款」→ 按序处理两个操作
发送无法处理的请求 → Webhook POST 发出
触发确认 → 30 分钟不操作 → 自动取消 → 重新发消息收到重试提示
加载电商模板 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 格式：

{
  "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：

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

7.0 KiB Raw Blame History Unescape Escape