87 lines
4.4 KiB
Markdown
87 lines
4.4 KiB
Markdown
# ADR-105: MCP Agent Loop Governance
|
||
|
||
**狀態**: Accepted
|
||
**日期**: 2026-05-01
|
||
**範圍**: MCP audit, Agent Loop, OpenClaw/NemoTron/Hermes/ElephantAlpha tool permissions
|
||
|
||
## 背景
|
||
|
||
AWOOOI 已有 MCP provider registry、K8s/SSH/Prometheus/Database/Grafana/RAG/Filesystem 等 provider、PreDecisionInvestigator、EvidenceSnapshot、PostExecutionVerifier。缺口不是「從零安裝 MCP」，而是：
|
||
|
||
- MCP 呼叫沒有統一 audit trail 與每日統計。
|
||
- PreDecisionInvestigator 是 Python pre-gathering 模式，LLM 看到結果但看不到 tool_use 過程。
|
||
- 不同 AI Agent 沒有可驗證的工具權限邊界。
|
||
- LLM retry storm 修掉後，需要讓真正的新 incident 能用 Agent Loop 深查，而不是回到靜態 prompt。
|
||
|
||
## 決策
|
||
|
||
### D1 — 保留 pre-gathering，新增 Agent Loop
|
||
|
||
PreDecisionInvestigator 仍是穩定 fallback。Agent Loop 作為 provider capability 漸進接入：
|
||
|
||
```text
|
||
Alert -> PreDecisionInvestigator -> EvidenceSnapshot -> LLM text decision
|
||
Alert -> Agent Loop -> LLM tool_use -> MCP tool_result -> Final Decision
|
||
```
|
||
|
||
任何 Agent Loop 超過 `max_iterations`、provider 不支援 tool_use、或工具權限不足時，必須降級回既有 pre-gathering / rule-first / Playbook RAG 路徑。
|
||
|
||
### D2 — 四 Agent 工具權限矩陣
|
||
|
||
| Agent | 允許 | 禁止 |
|
||
|-------|------|------|
|
||
| OpenClaw | 所有已註冊 MCP tool，由既有 safety gates 控制執行 | 無額外禁用 |
|
||
| NemoTron | Prometheus/Grafana/SignOz，K8s read-only | K8s restart/delete/scale/apply/patch |
|
||
| Hermes | Database、RAG、Filesystem、Prometheus | K8s/SSH 執行類操作 |
|
||
| ElephantAlpha | 全部 read-only | 任何寫入/通知/執行操作 |
|
||
|
||
權限定義在 `apps/api/src/services/ai_providers/permissions.py`，provider schema 轉換前必須先過濾。
|
||
|
||
### D3 — 統一 MCP audit
|
||
|
||
所有 registry provider 與 PDI tool registry provider 都包成 audited provider，寫入：
|
||
|
||
- `mcp_audit_log`
|
||
- `mcp_daily_stats`
|
||
|
||
`incident_id` 使用 `VARCHAR(64)`，因為 AWOOOI incident id 是 `INC-*` 字串，不是 UUID。Audit 必須包含 `agent_role`、`session_id`、`flywheel_node`、provider/tool、input/output、latency、success/error。
|
||
|
||
### D4 — MCP RAG 不獨立建 DB
|
||
|
||
內部 MCP RAG 沿用現有 PostgreSQL + pgvector + Redis hot cache：
|
||
|
||
- `knowledge_entries`
|
||
- `rag_chunks`
|
||
- `playbook_embeddings`
|
||
- existing KMWriter / KnowledgeRAG / PlaybookRAG
|
||
|
||
不另建獨立資料庫。原因：一致性、備份、incident/playbook join、權限治理都在同一 Postgres 邊界內已經存在。只有當向量資料量、查詢延遲、或多租戶隔離需要獨立擴展時，才評估外移專用 vector DB。
|
||
|
||
## 落地順序
|
||
|
||
1. P0: audit schema、agent_role、權限矩陣、tool schema、AgentToolExecutor。
|
||
2. P1: Claude/Ollama provider 接 `analyze_with_tools()`，但 DecisionManager 先 feature flag，不直接切主路徑。
|
||
3. P2: OpenClaw/NemoTron/Hermes/ElephantAlpha 逐一接線，先 read-only / diagnose，再開執行類工具。
|
||
4. P3: Langfuse spans、Grafana MCP dashboard、audit replay。
|
||
|
||
## 2026-05-01 P1 Canary
|
||
|
||
OpenClaw 先接 read-only shadow investigation，而不是直接替換主決策：
|
||
|
||
- Feature flag：`ENABLE_OPENCLAW_AGENT_LOOP_SHADOW`
|
||
- 輪數上限：`OPENCLAW_AGENT_LOOP_MAX_ITERATIONS`（prod canary 設 2）
|
||
- 觸發點：`OpenClawService.generate_incident_proposal_with_tools()` 原 proposal 成功後
|
||
- 允許工具：Kubernetes / Prometheus / SignOz / Database / RAG / Grafana 的 read-only tools
|
||
- Provider：本地 Ollama 優先，不新增 Gemini/Claude 付費呼叫
|
||
- 影響面：只附加 `agent_loop_shadow` metadata，不覆蓋 `action`、`risk_level`、`confidence` 或 Nemotron tool result
|
||
- Structured metadata：shadow raw response 需正規化為 `agent_loop_shadow.structured`，包含 `root_cause_check`、`evidence_used`、`confidence_delta`、`missing_evidence`、`human_or_ai_next_step`、`parse_status`
|
||
- Confidence delta：canary 階段只可記錄 0 到 -0.15 的保守 metadata，正值一律歸零；任何 score 或 auto-execute gate 變更需另開 ADR/Logbook 並通過 production audit
|
||
- 失敗策略：log warning 後回到既有 proposal / Nemotron / Playbook 路徑
|
||
|
||
## 驗收
|
||
|
||
- `mcp_audit_log` 24h call count > 0。
|
||
- 每筆 Agent Loop tool_use 有 `agent_role`。
|
||
- NemoTron / ElephantAlpha 無法取得 K8s 寫入工具。
|
||
- LLM ghost-loop 不因 Agent Loop 重啟：仍受 Alertmanager in-flight lock、stable cache、provider circuit breaker、max_iterations 控制。
|