# ADR-082: 多 Agent 協作架構（Phase 2）

> **日期**: 2026-04-15（台北）
> **狀態**: 🟢 批准（統帥 + 首席架構師共同簽核）
> **作者**: Claude Sonnet 4.6（首席架構師）+ 統帥 audit
> **相關**:
> - MASTER 藍圖：§3.2 D2 多 Agent 協作
> - ADR-081：Phase 1 感官縱深（前置）
> - HARD_RULES v1.9：Phase 退出條件鐵律

---

## 背景

Phase 1 完成後，AI 已具備「環境感知能力」（8D 感官 → EvidenceSnapshot）。
Phase 2 的目標是解決 LLM 的根本性弱點：**過度自信 + 幻覺**。

單一 OpenClaw 全包的問題：

| 問題 | 現象 |
|------|------|
| 沒有對抗機制 | LLM 說什麼信什麼，無內部質疑 |
| 根因與方案混為一談 | 根因判斷錯誤直接影響方案，無隔離 |
| 安全審查 = 無 | 危險指令只靠 HARD_RULES 靜態擋 |
| 無 Audit Trail | 無法追責「AI 為何做此決策」 |

## 決策

拆解單一 LLM 為 **5 個分工明確的 Agent**，用辯證 + 投票降低幻覺：

| Agent | 職責 | 輸入 | 輸出 |
|-------|------|------|------|
| **Diagnostician（偵探）** | RCA 根因分析 | `EvidenceSnapshot` | `DiagnosisReport` |
| **Solver（軍師）** | 對每個假設產方案 | `DiagnosisReport` | `ActionPlan` |
| **Reviewer（安全官）** | 安全審查 + 可行性 | `ActionPlan` | `ReviewVerdict` |
| **Critic（質疑者）** | 刻意唱反調，防幻覺 | `DiagnosisReport` + `ActionPlan` | `CriticReport` |
| **Coordinator（指揮官）** | 聚合辯證，拍板決策 | 全部 Agent 輸出 | `DecisionPackage` |

## 架構

```
EvidenceSnapshot
     │
     ▼
Diagnostician (3s)
     │  DiagnosisReport
     ▼
Solver (4s)
     │  ActionPlan
     ├─────────────────┐
     ▼                 ▼
Reviewer (3s)     Critic (3s)   ← 並行
     │ ReviewVerdict    │ CriticReport
     └────────┬─────────┘
              ▼
         Coordinator (2s)
              │  DecisionPackage
              ▼
        (回 decision_manager)
```

**時間預算**：P99 < 20s（含 Investigator 8s = Phase 1 已涵蓋）
**單 Agent 熔斷**：超時 5s → 降級為 rule-based mock，輸出「棄權」，不阻塞流程
**全流程熔斷**：> 30s → Coordinator 強制以現有資訊輸出結論並標 `degraded`

## Redis Streams 訊息匯流

Agent 間不直接 call function，透過 Redis Streams 傳訊：

- Stream Key: `aiops:agent:{session_id}`
- Consumer Group: 各 Agent 獨立消費自己的訊息
- 優勢：單一 Agent 掛掉不影響其他；可 replay 除錯

## AgentSession DB 表（Audit Trail）

每次辯證全程寫入 `agent_sessions`：

```
session_id / incident_id / agent_role / input_hash / output_json / latency_ms / created_at
```

- 不可刪除，只能新增（Immutable Event Sourcing）
- Phase 3 學習閉環依賴此表（記錄「Critic 是否挑戰成功」作為學習信號）

## 安全原則

- Reviewer 必須硬核拒絕任何觸碰 HARD_RULES 的動作（delete node / DROP TABLE 等）
- Critic prompt 強化「你的工作是找漏洞，不是順著說好話」（防 sycophancy）
- Agent 間不得修改彼此 prompt（防 prompt 污染擴散）
- 所有 Agent 輸出先過 `SanitizationService`（ADR-081 防注入）

## 回滾策略

```
AIOPS_P2_ENABLED=False → decision_manager 退回 Phase 1 單 LLM 路徑
```

- `agent_sessions` 表只新增，不影響任何舊表
- Orchestrator 熔斷設計：任一 Agent 失敗 → Coordinator 用現有資訊繼續

## Phase 2 退出條件

| 條件 | 量化指標 |
|------|---------|
| AgentSession 有資料 | 24h 內 ≥ 3 筆（Diagnostician / Solver / Coordinator 各 1）|
| 辯證有效 | 每事件 AgentSession turns ≥ 3 |
| Critic 工作 | CriticReport challenge_count > 0 至少 1 次 |
| 熔斷可用 | Diagnostician timeout → Coordinator 仍完成（降級路徑測試） |
| 延遲達標 | 多 Agent 路徑啟用後 p95 < 8s（避免拖垮主流程）|

## 不決定

- Agent 使用什麼 LLM（保持通過現有 `openclaw.call()` 路由，Phase 4 再優化模型分配）
- Agent 是否有「記憶」（Phase 3 再加 evidence_chain fine-tune）
- Declarative 修復（Phase 5）

---

*2026-04-15 ogt + Claude Sonnet 4.6（亞太）：Phase 2 正式批准*