awoooi/docs/adr/ADR-105-mcp-agent-loop-governance.md

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 漸進接入：

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 控制。