# 多智能体圆桌研讨 · 后端开发文档

本文档面向需要维护或扩展"多智能体圆桌研讨"功能后端的开发者。前端 API 速查请看 `multi-agent-api.md`,此文档关注**实现细节、设计取舍、性能特征**。

---

## 1. 功能定位

把"任务目标 + 用户约束"丢给一个**协调智能体**,由它通过 `agent_orchestration` 技能调度 6 个固定职能的子智能体（情报收集 / 环境评估 / 方案设计 / 风险审查 / 执行规划 / 总结陈述）协同产出方案,直到协调智能体认为信息足够、停止派活并输出最终结论为止。

对应前端页面：`/page/roundtable/planning` 的 **Step 2 多智能体研讨**。

---

## 2. 涉及的后端文件

```
offline-backend-20260512/backend/
├── app/gateway/
│   ├── app.py                       # 注册 multi_agent.router
│   └── routers/
│       └── multi_agent.py           # 本功能唯一新增的 router
└── .deer-flow/agents/
    ├── roundtable-intelligence/     # 6 个内置子智能体目录
    │   ├── config.yaml              #   ├── id / name / description
    │   └── SOUL.md                  #   └── 角色 prompt
    ├── roundtable-environment/
    ├── roundtable-solution-design/
    ├── roundtable-risk-review/
    ├── roundtable-execution-plan/
    └── roundtable-summary/
```

**零代码改动构造内置 agent**：6 个目录通过既有的 `_sync_legacy_agents()`（`app/gateway/routers/agents.py`）在下次任意 `/api/agents` 请求时自动 upsert 进 `agents` 表,`user_id IS NULL` 标记为内置。

---

## 3. 接口总览

路由前缀 `/api/multi-agent`，所有接口需要 `Authorization: Bearer <JWT>`。

| 方法 | 路径 | 用途 |
|---|---|---|
| POST | `/api/multi-agent/init` | 一次性创建协调智能体 + 6 个子席位线程,返回 `thread_ids` 映射 |
| POST | `/api/multi-agent/run/stream` | SSE 流式驱动一次 leader 或 special 调用 |

字段细节见 `multi-agent-api.md`,这里不重复。

---

## 4. 内部实现详解

### 4.1 `/init` 内部流程

```
[阶段1] 并行准备 6 个子智能体席位 (asyncio.gather)
  ├─ GET  /api/agents/{id}         × 6  → 取 name + description
  └─ POST /api/threads             × 6  → 建新 thread

[阶段2] 创建协调智能体
  ├─ POST /api/threads                  → 协调智能体的 thread
  └─ POST /api/agents (with model + skills=[agent_orchestration] + soul)
       └─ soul 里包含可调度的 6 个 agent_name + description 列表
```

**协调智能体 SOUL 是动态拼出来的**(`multi_agent.py:216-224`):

```python
soul = (
    "#核心定位：\n"
    "用途：根据用户的任务目标,调用其他智能体干活,只负责协调汇总,...\n"
    "#调度方法：\n"
    "通过使用agent_orchestration技能调用其他智能体干活,...\n"
    "#可调度智能体：\n"
    f"{descriptions}"  # ← 6 个子席位的 name+description
)
```

由于 `main_agent_name` 由前端每次新建（`roundtable-coordinator-{timestamp36}`）,所以协调智能体本身是一次性的、用完即弃。

### 4.2 `/run/stream` 内部流程

接收 `agent_type` 后走两条分支：

#### `agent_type = "leader"` (协调智能体)

```
1. broadcast「总控收到用户消息」到所有非自己线程  (asyncio.gather)
2. 拼 RunCreateRequest,转发到 POST /api/threads/{coordinator}/runs/stream
   - excluded_tools: ["web_search"]
   - context.model_name = 用户传的 model
3. 流式透传 LangGraph 事件给前端
4. 流结束后从最后一帧 values 取最末一条 message
5. 解析 message.tool_calls (agent_orchestration 技能调用):
   - 用 _extract_name_task() 提取 [agent_name, task_text]
   - 对每个 [agent_name, task]:
     broadcast「总控给 X 派活,内容为: ...」到所有非派活双方
6. 末尾追加状态帧:
   {
     "status": [["agent_name", "task"], ...],  // 空数组 = 共识达成
     "content": "<leader 最终文本>",
     "agent_name": "<coordinator>"
   }
```

#### `agent_type = "special"` (子智能体)

```
1. 拼 RunCreateRequest,转发到 POST /api/threads/{sub_agent}/runs/stream
   - excluded_tools: ["web_search","ask_clarification","present_files","view_image"]
2. 流式透传 LangGraph 事件
3. 流结束后从最后一帧 values 取交付内容 (content)
4. broadcast「子智能体 X 完成 Y 工作,交付内容为: ...」到所有非自己线程
5. 末尾追加状态帧:
   {
     "status": "子智能体 X 完成 Y 工作",
     "content": "<交付内容>",
     "agent_name": "<sub agent>"
   }
```

### 4.3 _broadcast 机制

```python
async def _broadcast(client, base, headers, message, agent_threads, skip):
    targets = [tid for name, tid in agent_threads.items() if name not in skip]
    await asyncio.gather(*(_append_thread_message(...) for tid in targets))
```

`_append_thread_message` 对每个目标 thread:

```
GET  /api/threads/{id}/state           # 拿当前 messages 列表
state.values.messages.append({"type":"human","content":...})
POST /api/threads/{id}/state           # 写回完整 state
```

这是**为了让每个子线程的对话历史里都能看到全局上下文**（其他席位说了什么、协调智能体怎么派活的）。子智能体下次被调用时,模型自然能基于这份"群消息回放"做判断。

**关键不变量**:`skip` 列表通常包含发起方和接收方,避免发起方收到回声、接收方收到重复消息。

---

## 5. 6 个内置 agent SOUL 设计要点

每个 `roundtable-*` 的 SOUL.md 遵循统一结构：

```
# {席位名}

## 角色定位
你是"多智能体圆桌研讨"会议的 **{席位}** 席位。会议由"总控协调智能体"统一调度,
你只在被派到任务时发言,不需要主动推动议程。

## 核心职责
- ...具体职责...

## 输出风格
- 每次发言以 {emoji} 开头
- 第一句直接给结论
- 不超过 4 句

## 边界
- 只产出 {本席位输出}
- 不替其他席位做 {其他席位输出}
- 任务结束后停下,等待总控派下一个任务

## 示例输出
> ...
```

| 席位 | agent_id | emoji | 核心职责 |
|---|---|---|---|
| 情报收集 | `roundtable-intelligence` | 📢 | 同类案例 + 历史风险预警 |
| 环境评估 | `roundtable-environment` | 🌍 | 硬件容量 + 量化承载力 |
| 方案设计 | `roundtable-solution-design` | 📐 | 主备方案 + 关键路径 |
| 风险审查 | `roundtable-risk-review` | ⚠️ | 合规红线 + 收敛建议 |
| 执行规划 | `roundtable-execution-plan` | 📅 | 里程碑 + 资源排布 |
| 总结陈述 | `roundtable-summary` | 🎤 | 归纳 + 冲突标记 + 盖印 |

**为什么不让子智能体自己调度**：所有 SOUL 都明文写了"只在被点到时发言,由总控协调智能体派活"。子智能体不装 `agent_orchestration` 技能。只有协调智能体装。这是单调度源,避免多智能体相互抢调度权造成的死循环。

---

## 6. 关键设计决策

### 6.1 为什么用 HTTP loopback 而不是内部函数调用

`multi_agent.py` 调用 `/api/threads`、`/api/agents`、`/api/threads/.../runs/stream` 都是用 `httpx` 走 `http://localhost:8001/...` 自身循环回来,而不是直接 `from app.gateway.services import ...`。

**好处**:
- 自动复用 Gateway 的鉴权 + CSRF + permission 中间件,不用再手写
- 复用既有路由的请求验证（Pydantic）和错误响应
- `Authorization` 头透传,被调端自然知道是哪个用户在调

**代价**: 每次调用都有一次额外的 TCP+JWT 解析开销（~10-50ms）。但因为 init 已经做了并行优化（A）、broadcast 已经省掉（C）,目前总体耗时是可接受的。

如未来需要进一步优化,可改为直接调用 `app/gateway/services.py` 里的内部函数,绕过 HTTP 一层。

### 6.2 为什么协调智能体每次新建

前端在每次进入 step 2 时生成 `roundtable-coordinator-{Date.now().toString(36)}`,作为 `main_agent_name`。

**好处**:
- 不同会话/不同用户/同一用户不同任务之间完全隔离
- 协调智能体的对话历史就是本次研讨的全部上下文,不会被上次任务污染
- SOUL 不会被"上次的可调度列表"覆盖（虽然现在 6 个席位是固定的）

**代价**: 每次都要在 `agents` 表插一行,`.deer-flow/agents/<id>/` 下生成新目录。长期会累积大量协调智能体目录,**未来需要清理脚本**（标记 description 以 "你是总控控制协调智能体" 开头的 agent 自动 GC）。

### 6.3 子智能体席位为什么固定 6 个

- 圆桌的 6 个角色定位是产品级强约束（情报/环境/方案/风险/执行/总结）
- 写在后端 SOUL.md 一处维护,跟其他内置 agent 同等地位
- 前端只需要把 6 个 hyphen-case 名作为 `agent_names` 传过来即可

如果后续要支持"用户自选席位",在前端加 mapping 面板让用户从 `GET /api/agents` 里挑,不动后端。

### 6.4 为什么 SSE 末尾还要追加一个 `{status:...}` 帧

LangGraph 原生 SSE 里没有"调度结果"这种语义,前端只能从最后一帧 values 里去翻 tool_calls。如果由前端解析,前后端协议会绑死 LangGraph 内部数据形状,迁移成本高。所以后端在流末尾追加一个**协议层的总结帧**:

```json
{
  "status": [["agent_name", "task"], ...] | "<完成提示>",
  "content": "<最终 AI 文本>",
  "agent_name": "<本轮 agent>"
}
```

前端 `streamMultiAgent` helper 通过 `isFinalStatusFrame()` 识别该帧（必须同时有 `status` + `content` 键）,与其他 LangGraph 帧区分。

---

## 7. 性能特征

### 7.1 已应用的优化

| ID | 优化 | 收益 |
|---|---|---|
| **A** | `/init` 阶段 1 并行化（`asyncio.gather`） | 阶段 1 从 2-4s 降到 0.3-0.7s |
| **C** | 删除 `/init` 末尾的 intro 广播（SOUL 已含定位） | 阶段 3 整段消失,省 1-2s |

应用前 `/init` 耗时 **3-8s**,应用后 **0.5-1.2s**。

### 7.2 仍然存在的开销点

| 调用 | 单次耗时 | 主因 |
|---|---|---|
| `GET /api/agents/{id}` | 50-300ms | 每次触发 `_sync_legacy_agents()` 扫整个 `.deer-flow/agents/` 目录(目前 30+ 项) |
| `POST /api/threads` | 100-200ms | LangGraph thread 表插入 + 默认 state 初始化 |
| `POST /api/agents` | 100-300ms | 文件系统写入 SOUL.md + config.yaml + agents 表 |
| `GET/POST /state` | 50-150ms × 2 | checkpointer 读写 |
| `POST /runs/stream` 启动 | 50-100ms | RunManager + StreamBridge 初始化 |
| LLM 推理 | **数百毫秒~数十秒** | 取决于 model + 上下文长度 |

**LLM 推理才是绝对大头**,基础设施开销在十几个百分点以内。

### 7.3 未来可探索

- **B**(已识别未做): broadcast 跳过 GET-state,直接 POST 新建态。但 POST 需要构造完整的 state shape,改造成本不小。
- **D**(已识别未做): loopback HTTP → 内部函数调用。代码改动大,但能省掉 ~20-30 次 HTTP 解析开销。

---

## 8. 依赖与扩展点

### 8.1 `agent_orchestration` 技能

协调智能体强依赖此技能,SOUL 里硬编码:

```
通过使用agent_orchestration技能调用其他智能体干活,使用技能时传入agent_name和需要做的活
```

技能的实际派活产物是一个形如 `python3 scripts/agent_orchestration.py "agent_name" "task"` 的 shell 调用文本,后端用正则提取：

```python
_TOOL_CALL_PATTERN = re.compile(r'\.py\s+"([^"]*)"\s+"([^"]*)"')
```

**若该技能被删除/改名**,leader 流程会拿不到 `tool_calls`,直接走"无派活=共识达成"分支。注意 `skills/` 下必须保留此技能。

### 8.2 模型选择

前端通过 `GET /api/models` 拿到列表,在 `model` 字段传 `Model.name` (与 `config.yaml.models[].name` 对应)。

- `/init` 的 `model` 字段 → 协调智能体的默认模型 (写进 agents 配置)
- `/run/stream` 的 `model` 字段 → 该次具体运行用什么模型 (写进 `context.model_name`)

前端允许"逐席位覆盖模型",由前端在 special 调用时按 `agentConfigs[seat].model` 传入。后端不感知"席位"概念,只看到 `model` 字段。

### 8.3 自定义新席位

如果要加第 7 个席位（比如"成本测算"）:

1. `.deer-flow/agents/roundtable-cost/` 加 `config.yaml` + `SOUL.md`
2. 前端 `RoundtablePlanningPage.tsx` 的 `ROUNDTABLE_ROLE_TEMPLATES` + `AGENT_NAME_TO_ROLE` 加映射
3. 圆桌可视化（圆圈环形图）加一个气泡 + 头像

**后端代码完全不需要改**。

---

## 9. 故障排查

| 现象 | 可能原因 | 排查 |
|---|---|---|
| `/init` 500 "create coordinator agent failed" | `agent_orchestration` 技能不存在 / config.yaml 写入失败 | 看后端日志 `multi_agent` logger;检查 `skills/` 目录 |
| `/run/stream` 502 "upstream returned HTTP 4xx" | JWT 过期 / 转发到上游时鉴权挂了 | 前端检查 Authorization 头是否带上 |
| leader 永远 `status: []` 立即结束 | 协调智能体没产生 `tool_calls`,直接给文本回答 | 协调智能体 SOUL 不够强、或模型不支持工具调用,换 model |
| special 内容为空 | 子智能体被 `excluded_tools` 限制到无可用工具 / 模型无文本输出 | 看上游 `runs/stream` 的 values 帧 messages.last.content |
| 进入 step 2 卡住转圈 | `/init` 超时或失败 | F12 Network 看 `/api/multi-agent/init` 状态码与响应体 |

### 服务端日志关键字

```bash
# multi_agent 路由的日志
grep "multi_agent" .runtime/logs/*.log

# 派活解析失败
grep "dispatch failed" .runtime/logs/*.log

# 广播失败（通常无害）
grep "update state .* failed" .runtime/logs/*.log
```

---

## 10. 测试入口

后端目前没有针对本功能的单测。建议补：

```
backend/tests/test_multi_agent.py
  - test_init_creates_threads_for_all_subagents
  - test_init_creates_coordinator_with_orchestration_skill
  - test_init_returns_400_when_agent_names_empty
  - test_stream_leader_emits_status_frame_with_content
  - test_stream_special_emits_status_frame_with_content
  - test_extract_name_task_parses_orchestration_skill_output
  - test_broadcast_skips_listed_agents
```

可用 `httpx.MockTransport` 拦截 loopback 请求,不依赖真实 Gateway。

---

## 11. 路径速查

| 资源 | 路径 |
|---|---|
| 路由实现 | `offline-backend-20260512/backend/app/gateway/routers/multi_agent.py` |
| 路由注册 | `offline-backend-20260512/backend/app/gateway/app.py`(`include_router(multi_agent.router)`) |
| 6 个内置 agent | `offline-backend-20260512/backend/.deer-flow/agents/roundtable-*/` |
| `agent_orchestration` 技能定义 | `skills/public/agent_orchestration/`(若存在) |
| 前端 API helper | `frontend-web/src/roundtable-planning/api/multi-agent.ts` |
| 前端页面 | `frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx` |
| 前端 API 速查 | `frontend-web/docs/multi-agent-api.md` |