7.7 KiB
7.7 KiB
问答模式路由智能体设计方案
状态：部分实现 ✓
- ✅
subagent_mode注入机制已实现（build_run_config、_CONTEXT_CONFIGURABLE_KEYS）- ✅ DeerFlow 运行时
subagent_mode加载已实现（make_lead_agent）- ✅
router_quality_tool.py已创建- ✅ 子 Agent 目录结构已创建（7个子 Agent 的 SOUL.md 和 config.yaml）
- ✅ 路由器 SOUL.md 已更新
- ⏳ 集成测试和质检提示词测试待完成
1. 背景与目标
路由器智能体（f0e75f44f7594053ba1567ed89258f35）根据用户问题判断最合适的问答模式（fast/rag/bigMode/moreModes/taskChat/hxchat/deerFlow），选择后需要调用相应子 Agent 执行，路由器对执行结果进行完整性质检，通过则流式输出到前端，不通过则重新匹配模式并再次执行。
2. 整体流程
用户问题
│
▼
┌──────────────────────────────┐
│ 路由器智能体 │
│ (已有 SOUL.md) │
│ ① 判断最佳模式 │
└─────────────┬────────────────┘
│ 选择模式
▼
┌──────────────────────────────┐
│ 子 Agent 执行 │
│ (完整执行完毕，结果缓存) │
└─────────────┬────────────────┘
│ 执行完毕
▼
┌──────────────────────────────┐
│ 路由器质检 │
│ LLM 判断结果是否完整覆盖用户问题 │
└─────────────┬────────────────┘
│
③ 质检结果
┌────┴────┐
│通过 │不通过
▼ ▼
流式输出 重新匹配模式
到前端 (最多重试2次)
- 最大重试次数：每个问题最多 2 次重试（总共最多 3 次执行），超过后强制输出当前结果并标注"结果可能不完整"
3. 目录结构
.deer-flow/agents/f0e75f44f7594053ba1567ed89258f35/
├── SOUL.md ← 路由器智能体（已有）
├── config.yaml ← 路由器配置
└── subagents/
├── fast/
│ ├── SOUL.md ← 快速问答子 Agent
│ └── config.yaml ← tool_groups 声明
├── rag/
│ ├── SOUL.md
│ └── config.yaml
├── bigMode/
│ ├── SOUL.md
│ └── config.yaml
├── moreModes/
│ ├── SOUL.md
│ └── config.yaml
├── taskChat/
│ ├── SOUL.md
│ └── config.yaml
├── hxchat/
│ ├── SOUL.md
│ └── config.yaml
└── deerFlow/
├── SOUL.md
└── config.yaml
父子关系：子 Agent 目录放在路由器下二级 subagents/，通过目录层级体现父子结构。
4. 子 Agent 配置
4.1 config.yaml 格式
id: rag
name: 知识库问答子Agent
description: 从知识库检索并返回引用
tool_groups:
- knowledge # 知识库检索工具组
- file:read # 只读文件工具
skills: []
model: deepseek-chat
4.2 tool_groups 说明
- tool_groups 在系统级
config.yaml中统一定义（tool_groups列表） - 子 Agent 的 config.yaml 通过
tool_groups字段声明自己可以使用哪些工具组 - 工具组示例：web（网页搜索）、knowledge（知识库检索）、file:read、file:write、bash 等
5. 调用方式
5.1 复用 Gateway API（方案 A — 推荐）
路由器通过 DeerFlow 现有 /api/threads/{thread_id}/runs/stream 接口调用子 Agent：
POST /api/threads/{thread_id}/runs/stream
{
"assistant_id": "f0e75f44f7594053ba1567ed89258f35",
"context": {
"subagent_mode": "rag" ← 路由器注入子模式
},
"input": {
"messages": [...]
},
"stream_mode": ["values"]
}
执行步骤：
- 路由器启动一个 run，assistant_id 指向路由器本身
- 路由器通过
context.subagent_mode告知 DeerFlow 运行时本次应加载哪个子 Agent - DeerFlow 运行时加载
subagents/{subagent_mode}/SOUL.md和对应的 tool_groups - 子 Agent 完整执行，结果缓存在 StreamBridge 中
- 执行完毕后，路由器读取完整结果
context.subagent_mode 注入机制：
build_run_config中新增subagent_mode到_CONTEXT_CONFIGURABLE_KEYSmake_lead_agent读取configurable.subagent_mode，如果存在则加载对应子 Agent 的 SOUL.md 和工具配置- 如果
subagent_mode不存在，则正常运行路由器自己的 SOUL.md
5.2 质检提示词
路由器在子 Agent 执行完毕后，用 LLM 进行完整性质检：
你是一个质检员。上游子 Agent 已根据问题执行完毕。
请判断以下结果是否完整覆盖了用户问题的所有子问题。
用户原始问题：{original_question}
子 Agent 执行结果：
{agent_output}
请只返回 JSON 格式：
{
"passed": true/false,
"reason": "判断理由（10字内）",
"missing_parts": ["缺失的子问题1", "缺失的子问题2"] // 如果 passed=false
}
质检维度：完整性（结果是否覆盖了用户问题的所有子问题）
6. 关键代码改动
6.1 DeerFlow 运行时改动 ✓
文件：packages/harness/deerflow/agents/lead_agent/agent.py
已实现：
make_lead_agent读取configurable.subagent_mode（第362-394行）- 如果存在，加载
.deer-flow/agents/{agent_id}/subagents/{subagent_mode}/SOUL.md和对应config.yaml - 工具绑定使用子 Agent 的 tool_groups，而非父 Agent 的
6.2 build_run_config 改动 ✓
文件：app/gateway/services.py
已实现：
_CONTEXT_CONFIGURABLE_KEYS已包含subagent_mode（第149-171行）merge_run_context_overrides将subagent_mode透传到 configurable
6.3 路由器 SOUL.md 改动 ✓
文件：.deer-flow/agents/f0e75f44f7594053ba1567ed89258f35/SOUL.md
已更新：
- 角色扩展：增加"在确定模式后，调用相应子 Agent 执行并对结果进行质检"的职责
- 工具描述：已声明 router_quality_check 工具
6.4 新增路由器质检工具 ✓
文件：packages/harness/deerflow/tools/builtins/router_quality_tool.py
已实现：
@tool("router_quality_check", parse_docstring=True, return_direct=True)
def router_quality_check(original_question: str, agent_output: str) -> str:
"""质检工具 — 判断子 Agent 输出是否完整覆盖用户问题"""
7. 数据流
用户问题
│
▼
路由器 SOUL.md 判断模式
│
▼
启动子 Agent Run（context.subagent_mode = rag）
│
▼
子 Agent SOUL.md + tool_groups 执行
│
▼
StreamBridge 缓存完整结果
│
▼
路由器调用 router_quality_check 质检
│
├── passed=true → 流式输出到前端
└── passed=false → 重新匹配模式（最多2次重试）
8. 测试计划
- 单元测试：
tests/test_router_subagent.py— 测试模式判断、质检逻辑、重试机制 - 集成测试：手动调用
/api/threads/{thread_id}/runs/stream，验证完整流程 - 质检提示词测试：针对不同问题类型测试质检结果的准确性
9. 依赖项
- 路由器复用现有 Gateway API，无需新建接口
- 质检使用 LLM（deepseek-chat 或配置中指定的模型）
- tool_groups 机制依赖系统级 config.yaml 中的工具组定义