530 lines
18 KiB
Markdown
530 lines
18 KiB
Markdown
# Agent 架构设计（MVP 版）
|
||
|
||
## 一、MVP 全景
|
||
|
||
```
|
||
用户输入
|
||
↓
|
||
┌──────────────────────────────────────────┐
|
||
│ 意图识别（Intent Recognition） 🆕 │
|
||
│ "用户想干什么？" │
|
||
│ │
|
||
│ 诊断意图 → 路由到诊断 Skill │
|
||
│ 文档意图 → 路由到文档问答 │
|
||
│ 案例意图 → 路由到案例查询 │
|
||
│ 闲聊 → 快速响应（不启动 Agent） │
|
||
│ 模糊/无关 → 提示用户，直接中断 │
|
||
└──────────────┬───────────────────────────┘
|
||
│ 诊断意图
|
||
↓
|
||
┌──────────────────────────────────────────┐
|
||
│ Supervisor Agent（调度者） │
|
||
│ "谁来干？什么时候停？" │
|
||
└──────────────┬───────────────────────────┘
|
||
↓
|
||
┌──────────────────────────────────────────┐
|
||
│ Planner Agent（规划者） │
|
||
│ 分析问题 → 制定策略 → 生成报告 │
|
||
└──────────────┬───────────────────────────┘
|
||
↓
|
||
┌──────────────────────────────────────────┐
|
||
│ Executor Agent（执行者） │
|
||
│ 调用工具收集证据 │
|
||
└──────────────┬───────────────────────────┘
|
||
↓
|
||
┌──────────────────────────────────────────┐
|
||
│ Verifier Agent（验证者） │
|
||
│ 事实核查 → 判定通过/修正/驳回 │
|
||
└──────────────┬───────────────────────────┘
|
||
↓
|
||
诊断报告输出
|
||
↓
|
||
用户反馈（有用/无用）
|
||
↓
|
||
案例沉淀 + BadCase 优化
|
||
```
|
||
|
||
---
|
||
|
||
## 二、意图识别（入口层）🆕
|
||
|
||
### 2.1 设计理念
|
||
|
||
```
|
||
定位：独立模块，不嵌入任何单一 Agent
|
||
|
||
分层策略（不是二选一，而是组合）：
|
||
|
||
L0: 正则规则 —— 0 成本，毫秒级 ✅ MVP
|
||
├─ 处理 80%+ 的结构化查询
|
||
├─ 正则匹配订单号/traceId/错误码格式
|
||
└─ 关键词匹配（"报错"/"异常"/"失败"）
|
||
|
||
L1: 小模型 Agent —— 低成本，百毫秒级 ✅ MVP
|
||
├─ L0 未命中时触发
|
||
├─ 处理灵活的模糊表达（"系统有点慢"、"怎么查不到了"）
|
||
├─ 不启动全链路 Agent，只做意图分类
|
||
└─ 判断为诊断意图 → 路由到诊断 Skill
|
||
|
||
L2: 兜底策略 —— 极少使用
|
||
├─ L0+L1 都无法判断 → 意图不明 → 中断
|
||
└─ Phase 2 增强
|
||
```
|
||
|
||
### 2.2 意图分类与路由
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────┐
|
||
│ 意图 │ 说明 │ 路由 │
|
||
├────────────────────────────────────────────────────┤
|
||
│ 诊断意图 │ 包含结构化标识或错误描述 │ → 诊断Skill│
|
||
│ 文档问答 │ "XX接口的参数有哪些" │ → 直接RAG │
|
||
│ 案例查询 │ "之前有类似的问题吗" │ → 案例检索 │
|
||
│ 闲聊 │ "你好"/"谢谢" │ → 快速响应 │
|
||
│ 意图不明 │ 无法识别 │ → 中断+提示 │
|
||
└────────────────────────────────────────────────────┘
|
||
|
||
关键原则：
|
||
- 只有诊断意图才启动 Agent 全链路
|
||
- 非诊断意图走轻量路径或直接中断
|
||
```
|
||
|
||
### 2.3 L0：正则规则（MVP，处理 80%）
|
||
|
||
```
|
||
为什么先做 L0？
|
||
→ 0 成本（不调 LLM），毫秒级响应
|
||
→ 结构化查询占比最大（订单号、traceId、错误码、关键词）
|
||
→ L0 命中直接路由，不需要走后续逻辑
|
||
|
||
规则配置（可扩展）：
|
||
┌────────────────────────────────────────────────┐
|
||
│ 规则 │ 意图 │ 方式 │
|
||
├────────────────────────────────────────────────┤
|
||
│ 匹配 \d{12,} │ 诊断 │ 正则 │
|
||
│ 匹配 trace[-_]?\w{8,} │ 诊断 │ 正则 │
|
||
│ 包含"报错‖失败‖异常‖挂了‖超时" │ 诊断 │ 关键词│
|
||
│ 包含"文档‖接口‖参数‖字段‖API" │ 文档 │ 关键词│
|
||
│ 包含"案例‖之前‖类似‖历史" │ 案例 │ 关键词│
|
||
│ 长度 <= 5 字符 │ 闲聊 │ 规则 │
|
||
└────────────────────────────────────────────────┘
|
||
|
||
命中 → 直接路由，不调 L1
|
||
未命中 → 进入 L1
|
||
```
|
||
|
||
### 2.4 L1：小模型 Agent（MVP，处理剩余 20%）
|
||
|
||
```
|
||
为什么用小模型 Agent 而非嵌入到 Supervisor？
|
||
→ 意图识别是独立职责，不应耦合到任何业务 Agent
|
||
→ 轻量 Agent：单一职责，只分类不执行
|
||
→ 成本低（~50 token），延迟低（~200ms）
|
||
|
||
何时触发：L0 规则未命中
|
||
|
||
System Prompt:
|
||
"你是意图分类器，判断用户想做什么。
|
||
只返回一个词：[诊断 / 文档查询 / 案例查询 / 闲聊 / 意图不明]
|
||
|
||
诊断：用户描述了故障、报错、异常
|
||
文档查询：用户询问接口文档、字段含义
|
||
案例查询：用户询问历史案例、类似问题
|
||
闲聊：简单的问候、感谢
|
||
意图不明：无法判断用户意图"
|
||
|
||
输入：用户原始输入
|
||
输出：意图类型 + 置信度
|
||
```
|
||
|
||
### 2.5 L2：兜底策略
|
||
|
||
```
|
||
L0+L1 都无法判断 → L2 兜底
|
||
|
||
中断规则：
|
||
├─ 意图不明 → 提示用户 + 中断
|
||
│ "无法判断您的意图，请提供订单号或错误码"
|
||
├─ 闲聊 → 快速响应 + 中断
|
||
│ "我是故障诊断助手，请描述您遇到的问题"
|
||
└─ 不启动 Agent，直接返回
|
||
|
||
路由规则：
|
||
├─ 诊断意图 → 启动 Supervisor + 4 Agent 全链路
|
||
├─ 文档意图 → 不启动 Agent，直接 RAG 检索
|
||
└─ 案例意图 → 不启动 Agent，直接查询 case_library
|
||
```
|
||
|
||
### 2.5 架构位置
|
||
|
||
```
|
||
用户输入
|
||
↓
|
||
┌──────────────────────────────────────────┐
|
||
│ 意图识别模块（独立） │
|
||
│ │
|
||
│ L1: 小模型 Agent ─→ 诊断意图？ │
|
||
│ │ 文档意图？ │
|
||
│ │ 案例意图？ │
|
||
│ │ 闲聊？ │
|
||
│ ↓ │
|
||
│ L2: 兜底 ─────────→ 意图不明 → 中断 │
|
||
│ 闲聊 → 快速响应 │
|
||
└───────────────┬──────────────────────────┘
|
||
│ 诊断意图
|
||
↓
|
||
Supervisor → Planner → Executor → Verifier
|
||
```
|
||
|
||
### 2.6 MVP vs Phase 2
|
||
|
||
```
|
||
MVP L0（正则）+ L1（小模型Agent） 覆盖 95%+ 场景
|
||
Phase 2 L2（兜底增强） 细化中断提示，支持多轮澄清
|
||
```
|
||
|
||
---
|
||
|
||
## 三、4 个 Agent 设计
|
||
|
||
### 2.1 Supervisor Agent（调度者）
|
||
|
||
**职责**：总指挥，协调工作流
|
||
|
||
```
|
||
调度规则：
|
||
├─ 接收任务 → 发给 Planner 分析
|
||
├─ Planner 完成 → 发给 Executor 执行
|
||
├─ Executor 完成 → 发给 Verifier 校验
|
||
└─ Verifier PASS → 输出报告 / REJECT → 返回 Planner 重新规划
|
||
|
||
不做：
|
||
- 不直接调用工具
|
||
- 不直接生成报告
|
||
```
|
||
|
||
### 2.2 Planner Agent（规划者 + 分诊）
|
||
|
||
**职责**：分析问题、制定策略、生成报告草稿
|
||
|
||
```
|
||
分析规则：
|
||
├─ 有 errorCode + 接口 URL → EXTERNAL_API（外部接口故障）
|
||
├─ 有堆栈信息 → INTERNAL_ERROR（系统内部错误）
|
||
├─ 有数据库错误码（如 1213）→ DATABASE（数据库问题）
|
||
└─ 其他 → 通用排查
|
||
|
||
规划流程：
|
||
1. 确定 fault_category
|
||
2. 制定排查步骤（每步：工具名 + 参数 + 预期）
|
||
3. 生成决策：EXECUTE（继续执行）| FINISH（生成报告）
|
||
|
||
Replanner 职责：
|
||
├─ Executor 每次返回结果后 → 评估证据是否充分
|
||
├─ 需要补充？→ 调整步骤，继续执行
|
||
├─ 证据齐全？→ FINISH，生成报告草稿
|
||
└─ 连续 3 次失败？→ 降级
|
||
|
||
禁止：
|
||
- 编造数据
|
||
- 引用未经工具返回的内容
|
||
```
|
||
|
||
### 2.3 Executor Agent（执行者）
|
||
|
||
**职责**：调用工具收集证据
|
||
|
||
```
|
||
工具清单：
|
||
├─ queryOrder：查询订单/业务数据（MySQL 只读）
|
||
├─ searchDoc：检索接口文档（混合检索 Milvus + MySQL）
|
||
├─ recommendCase：推荐相似案例（精确匹配 + 语义检索）
|
||
└─ getCurrentTime：获取当前时间
|
||
|
||
执行规则：
|
||
├─ 每次只执行 Planner 指定的一个步骤
|
||
├─ 返回结构化的执行结果
|
||
├─ 失败时返回错误详情（便于 Planner 调整）
|
||
└─ 禁止编造结果
|
||
|
||
扩展预留：
|
||
// 代码中 Executor 是接口，后续可扩展为 SubAgent
|
||
public interface Executor {
|
||
ExecutionResult execute(Step step);
|
||
}
|
||
```
|
||
|
||
### 2.4 Verifier Agent（验证者）
|
||
|
||
**职责**：验证诊断报告，防止编造
|
||
|
||
```
|
||
验证流程：
|
||
|
||
1️⃣ 事实核查（最重要）
|
||
├─ 报告中的错误码 → 在 tool_calls 中存在？
|
||
├─ 根因结论 → 有日志/文档证据支撑？
|
||
├─ 修复方案 → 引用了文档或案例？
|
||
└─ 发现编造数据 → 直接 REJECT
|
||
|
||
2️⃣ 完整性检查
|
||
├─ 根因分析章节不能为空
|
||
├─ 证据链章节不能为空
|
||
└─ 修复方案章节不能为空
|
||
|
||
判决结果：
|
||
├─ PASS：报告成立，直接输出
|
||
├─ REVISE：小问题可修正，返回 Planner 微调
|
||
└─ REJECT：编造数据或严重错误，返回 Planner 重新分析
|
||
```
|
||
|
||
---
|
||
|
||
## 四、RAG 两层加载策略
|
||
|
||
### 4.1 设计理念
|
||
|
||
```
|
||
问题：
|
||
❌ 全前置：启动时把所有文档塞给 Agent → 信息过载，推理变慢
|
||
❌ 纯被动：等到需要才查 → Planner 没有全局视野，可能跑偏
|
||
❌ 固定步骤：每次都调 → 内部错误查接口文档浪费
|
||
|
||
正确做法：两层互补
|
||
|
||
L1 预加载（Planner 启动时）
|
||
→ 通用领域知识：系统架构、通用错误码、业务流程
|
||
→ 给 Planner 全局视野，避免方向性错误
|
||
|
||
L2 按需加载（Executor 执行中）
|
||
→ 具体接口文档：字段定义、错误码含义、调用规范
|
||
→ 给 Executor 精准证据，定位具体问题
|
||
```
|
||
|
||
### 4.2 两层对比
|
||
|
||
| | L1 预加载 | L2 按需加载 |
|
||
|------|---------|-----------|
|
||
| 触发时机 | 意图识别后，Planner 启动前 | Executor 拿到具体信息后 |
|
||
| 内容 | 通用知识（架构、流程、高频错误码） | 具体接口文档（字段、错误码含义） |
|
||
| 目的 | 让 Planner 有全局视野 | 让 Executor 有精准证据 |
|
||
| 成本 | 固定，每次诊断 1 次 | 按需，最多 2-3 次 |
|
||
| 谁负责 | Supervisor 注入 | Executor 自主调用 |
|
||
|
||
### 4.3 实现方式
|
||
|
||
```
|
||
L1 预加载：
|
||
Supervisor 在启动 Planner 前：
|
||
searchDoc(keyword="系统架构 通用错误码 业务流程")
|
||
→ 注入到 Planner 的 System Prompt 中
|
||
→ Planner 拥有"领域背景知识"
|
||
|
||
L2 按需加载：
|
||
Executor 执行 Step 2 时：
|
||
拿到 errorCode=40003, faultSource="广东"
|
||
→ 自主调用 searchDoc(errorCode="40003", faultSource="广东")
|
||
→ 获取该接口的具体字段定义和错误码说明
|
||
→ 作为证据写入诊断报告
|
||
```
|
||
|
||
---
|
||
|
||
## 五、Skill 设计（1 个）
|
||
|
||
### /diagnose-by-orderid（按订单号诊断）
|
||
|
||
```
|
||
输入：orderId
|
||
|
||
工作流（6 步）：
|
||
|
||
Step 1: 查询订单信息
|
||
工具：queryOrder
|
||
失败：ABORT（订单不存在则终止）
|
||
|
||
Step 2: 检索接口文档
|
||
工具：searchDoc
|
||
参数：errorCode + faultSource
|
||
失败：SKIP（标注"文档缺失"）
|
||
|
||
Step 3: 查询日志
|
||
工具：queryLogs（Mock）
|
||
参数：traceId
|
||
失败：SKIP（标注"日志缺失"）
|
||
|
||
Step 4: 检索相似案例
|
||
工具：recommendCase
|
||
参数：errorCode + faultCategory
|
||
失败：SKIP（标注"无相似案例"）
|
||
|
||
Step 5: 生成诊断报告
|
||
汇总所有证据，按模板生成报告
|
||
|
||
Step 6: Verifier 验证
|
||
事实核查 → 判决
|
||
|
||
门禁规则：
|
||
├─ Step 1 失败 → 终止，返回"订单不存在"
|
||
├─ Step 2-4 失败 → 跳过，标注缺失信息
|
||
├─ 任意步骤超时 30s → 终止
|
||
└─ Verifier REJECT → 返回 Planner 重新规划
|
||
```
|
||
|
||
---
|
||
|
||
## 六、Harness 控制层（精简版）
|
||
|
||
### 4.1 5 个 Quality Gates
|
||
|
||
```
|
||
输入门禁（2 个）：
|
||
├─ Gate 1: 输入参数非空校验
|
||
└─ Gate 2: 5 分钟内同一订单 → 返回缓存
|
||
|
||
执行门禁（1 个）：
|
||
└─ Gate 3: 工具调用超时（10 秒）
|
||
|
||
输出门禁（2 个）：
|
||
├─ Gate 4: 报告章节完整性（3 章节不全 → 不通过）
|
||
└─ Gate 5: 置信度阈值（< 60 → 标记"低置信度"）
|
||
```
|
||
|
||
### 4.2 中断规则
|
||
|
||
```
|
||
自动中断：
|
||
├─ 工具连续失败 3 次 → 终止，降级输出
|
||
└─ 全局超时 30 秒 → 终止
|
||
|
||
条件降级：
|
||
├─ 文档检索为空 → 跳过继续
|
||
├─ 案例推荐为空 → 跳过继续
|
||
└─ 日志查询失败 → 跳过继续
|
||
|
||
降级输出：
|
||
"无法自动诊断，请人工介入"
|
||
+ 已收集的证据（订单信息 + 部分日志 + 已知错误码）
|
||
```
|
||
|
||
---
|
||
|
||
## 七、技术实现
|
||
|
||
### 5.1 基于 Spring AI Alibaba
|
||
|
||
```java
|
||
// Supervisor - 框架提供
|
||
SupervisorAgent supervisor = SupervisorAgent.builder()
|
||
.name("diagnosis_supervisor")
|
||
.model(chatModel)
|
||
.subAgents(List.of(planner, executor, verifier))
|
||
.build();
|
||
|
||
// Planner
|
||
ReactAgent planner = ReactAgent.builder()
|
||
.name("planner_agent")
|
||
.model(chatModel)
|
||
.systemPrompt(plannerPrompt)
|
||
.outputKey("planner_plan")
|
||
.build();
|
||
|
||
// Executor（代码中预留 SubAgent 扩展接口）
|
||
ReactAgent executor = ReactAgent.builder()
|
||
.name("executor_agent")
|
||
.model(chatModel)
|
||
.systemPrompt(executorPrompt)
|
||
.methodTools(diagnosisTools)
|
||
.tools(new ToolCallback[]{queryOrder, searchDoc, recommendCase, getCurrentTime})
|
||
.build();
|
||
|
||
// Verifier
|
||
ReactAgent verifier = ReactAgent.builder()
|
||
.name("verifier_agent")
|
||
.model(chatModel)
|
||
.systemPrompt(verifierPrompt)
|
||
.outputKey("verifier_result")
|
||
.build();
|
||
```
|
||
|
||
### 5.2 工具注册
|
||
|
||
```java
|
||
@Component
|
||
public class DiagnosisTools {
|
||
|
||
@Tool(description = "查询订单/业务数据（只读）")
|
||
public OrderInfo queryOrder(@ToolParam(description = "订单号") String orderId) {
|
||
// MySQL 只读 + SQL 注入防护
|
||
}
|
||
|
||
@Tool(description = "检索接口文档")
|
||
public List<DocChunk> searchDoc(
|
||
@ToolParam(description = "错误码") String errorCode,
|
||
@ToolParam(description = "省份/服务名") String faultSource
|
||
) {
|
||
// 混合检索：精确匹配 + 向量检索
|
||
}
|
||
|
||
@Tool(description = "推荐相似历史案例")
|
||
public List<CaseResult> recommendCase(
|
||
@ToolParam(description = "错误码") String errorCode,
|
||
@ToolParam(description = "故障类别") String faultCategory
|
||
) {
|
||
// 精确匹配 MySQL + 语义检索 Milvus
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 八、闭环机制
|
||
|
||
```
|
||
诊断报告输出
|
||
↓
|
||
用户反馈（useful / not_useful）
|
||
↓
|
||
├─ useful → 自动生成 case_library
|
||
└─ not_useful → 记录 BadCase
|
||
↓
|
||
每周 BadCase 分析
|
||
↓
|
||
Prompt / Skill 优化
|
||
↓
|
||
准确率验证（测试集重跑）
|
||
```
|
||
|
||
---
|
||
|
||
## 九、MVP vs 扩展方向
|
||
|
||
| 维度 | MVP | 扩展方向 |
|
||
|------|-----|---------|
|
||
| Agent | 4 个 Agent | SubAgent 模式（专科医生） |
|
||
| Skill | 1 个 | 渐进式披露（3 层知识） |
|
||
| 工具 | @Tool 注解 | MCP 独立 Server |
|
||
| 回退 | 2 级（失败→降级） | 4 级路由 |
|
||
| Gates | 5 个 | 15 个全流程门禁 |
|
||
| 隔离 | 单 JVM | K8s Pod 进程隔离 |
|
||
| 进化 | 案例自动生成 | 模式识别 + Prompt 自优化 |
|
||
|
||
---
|
||
|
||
## 十、面试话术（精简版）
|
||
|
||
> "我用 Spring AI Alibaba 实现了一个故障诊断 Agent 系统。
|
||
>
|
||
> 入口层是**意图识别**：先判断用户想干什么——诊断故障、查文档、查案例还是闲聊。
|
||
> 非诊断意图直接走轻量路径，只有诊断意图才启动 Agent 全链路，节省资源。
|
||
>
|
||
> 4 Agent 协作：Supervisor 调度、Planner 制定策略、
|
||
> Executor 调用工具收集证据、Verifier 验证报告防止编造。
|
||
>
|
||
> 诊断流程封装成了 Skill，标准化 6 个步骤和异常处理。
|
||
> Harness 层 5 个门禁保证质量——最关键的是输出门禁，
|
||
> Verifier 会对比报告数据和工具返回数据，发现编造就驳回。
|
||
>
|
||
> 闭环机制：用户反馈 → BadCase 分析 → Prompt 优化。
|
||
> 案例自动沉淀，系统越用越智能。"
|