Sarathpavan2001/sentinel-multi-agent-incident-response

# Sentinel — 多智能体网络运营指挥中心 ## 问题陈述 **Sentinel** 使用多智能体系统自动化了这一分诊过程，其中专家智能体会独立进行调查，可能真正对彼此的假设产生分歧，并且必须在事件关闭前通过结构化的协商循环来消除分歧——这正是真实 NOC 作战室的实际运作方式。 ## 架构 ``` ┌─────────────┐ │ Monitoring │ │ Agent │ └──────┬──────┘ │ ┌───────────────┼───────────────┐ │ │ │ v v v ┌──────────────┐ ┌────────────┐ ┌───────────────┐ │ Root Cause │ │ Capacity │ │ Customer │ │ Agent │ │ Agent │ │ Impact Agent │ └──────┬───────┘ └─────┬──────┘ └───────┬───────┘ │ │ │ └───────────────┼────────────────┘ │ v ┌─────────────────────┐ │ Incident Commander │◄────────────────┐ │ (Reconciliation) │ │ └──────────┬──────────┘ │ │ │ ┌──────┴──────┐ ┌─────┴──────┐ │ Conflict? │──── YES ────►│ Dispatcher │ └──────┬──────┘ └─────┬──────┘ │ NO │ v ┌──────┴──────┐ ┌─────────────────┐ │ Root Cause │ │ Remediation │ │ + Capacity │ │ Agent │ │ (Re-eval) │ └────────┬────────┘ └─────────────┘ │ v ┌─────────────────┐ │ Postmortem │ │ Agent │ └────────────────┘ ``` ### 为什么这是真正的多智能体 大多数“多智能体”演示都是线性管道——Agent A 传递给 Agent B 再传递给 Agent C。Sentinel 在架构上完全不同： 1. **具有真正独立性的并行扇出**：Root Cause、Capacity 和 Customer Impact 智能体通过 LangGraph 的原生并行边缘调度并发运行。Root Cause 和 Capacity 在第一轮中*无法看到彼此的输出*——它们的分歧是真实的，而非预先安排的。 2. **通过 `add_conditional_edges` 实现的条件协调循环**：当 Incident Commander 检测到冲突时（不同的 `root_cause_type` 且两个智能体的置信度均高于 0.6），它会生成一个针对性的问题，并将路由*返回*给两个调查智能体。这是图中的真正循环，而不是重试包装器。 3. **可靠的升级机制**：如果智能体在 2 轮之后仍无法达成一致，系统将进行升级，而不是强制虚假收敛。这就是真实 NOC 作战室的工作方式——有时答案就是“我们需要人类介入”。 4. **Human-in-the-loop 关卡**：Remediation Agent 会提出操作建议，但当严重程度为高/危重或操作不可逆时，不会自动执行。事件进入 `pending_approval` 状态，并需要通过 `/incident/{id}/approve` 端点获得明确的人工批准。 5. **自我完善的知识库**：Postmortem Agent 会编写新的 runbook 条目并重新索引 FAISS 向量存储，因此两次运行相同的场景类型在第二次会产生更丰富的 SOP 上下文。 ## 技术栈 | 层级 | 选择 | 原因 | |---|---|---| | 编排 | **LangGraph** (`StateGraph`) | 原生支持条件边缘 + 循环 = 真正的智能体协商 | | LLM | **Gemini Flash** (`google-generativeai` + `langchain-google-genai`) | 集中式客户端处理结构化输出；LangChain 绑定用于工具调用智能体 | | 智能体框架 | **LangChain** 工具调用模式 | 匹配 DTDL 技能需求 | | RAG 存储 | **FAISS** (本地，内存中) | 零外部依赖，检索速度快 | | Embeddings | **Gemini Embedding** (`models/gemini-embedding-001`) | 与 LLM 调用使用相同的 API key，无需单独下载模型 | | 后端 API | **FastAPI** (异步) | 原生异步支持，自动生成 OpenAPI 文档 | | 校验 | **Pydantic v2** | 对每个 LLM 决策点进行结构化输出校验 | | 配置 | **pydantic-settings** + `.env` | 安全的密钥管理 | | 日志记录 | 结构化 JSON 写入文件 | 具备可观测性的审计追踪 | ## 设置与运行 ### 前置条件 - Python 3.10+ - 一个 Google Gemini API key ### 安装 ``` cd sentinel python -m venv .venv # Windows .venv\Scripts\activate # macOS/Linux source .venv/bin/activate pip install -r requirements.txt ``` ### 配置 ``` cp .env.example .env # 编辑 .env 并添加你的 GEMINI_API_KEY ``` ### 构建 RAG 索引 ``` python -m app.rag.build_index ``` ### 运行演示场景 ``` # 冲突场景（核心部分 — agents 产生分歧并进行调和） python run_demo.py scenarios/scenario_conflict.json # 一致场景（顺利收敛，无冲突） python run_demo.py scenarios/scenario_agree.json ``` ### 运行 API 服务器 ``` uvicorn app.main:app --reload ``` **端点：** - `GET /` — Agent Trace Viewer UI（单页应用） - `POST /incident/trigger` — 启动新的事件调查 - `GET /incident/{id}` — 获取当前事件状态 - `GET /incident/{id}/trace` — 获取完整的智能体追踪数据（工具调用、LLM 迭代、假设） - `POST /incident/{id}/approve` — 批准待处理的修复 - `GET /metrics` — Prometheus metrics 端点 - `GET /health` — 健康检查 ### 运行测试 ``` pytest tests/ -v ``` ## 演示：冲突场景追踪 冲突场景（`scenario_conflict.json`）演示了 Sentinel 的核心能力。设置如下： - **区域**：ap-south-1 (孟买) - **服务**：video-streaming - **背景**：ICC 冠军杯半决赛直播（420 万并发用户） - **异常**：部署 v2.3.1 于 14:02 上线，但由于板球比赛，流量从 14:00 开始就已经在飙升 - **指标**：12.4% 的错误率，延迟是基线的 10 倍，6 个不健康实例，CDN 缓存命中率从 94% 骤降至 62% **执行流程：** 1. **Monitoring Agent** 根据指标将严重程度分类为高/危重 2. **Root Cause Agent** 看到 14:02 的 v2.3.1 部署（大型变更集，47 个文件，新的编解码器依赖项），并以高置信度假设为 `bad_deployment` 3. **Capacity Agent** 看到高峰事件期间流量是基线的 1.5 倍，6/24 个实例不健康，auto-scaling 尚未达到极限，并以高置信度假设为 `load_spike` 4. **Incident Commander** 检测到冲突——两个智能体的置信度都在 0.6 以上但根本原因不同——并针对部署时间戳与负载激增开始时间之间 2 分钟的重叠期生成了一个针对性的问题 5. 两个智能体以 IC 的问题作为额外上下文进行重新评估 6. 它们要么达成一致（其中一个调整置信度/类型），要么 IC 在达到最大轮数后进行升级 7. **Remediation Agent** 提出具体的行动方案（例如：回滚 + 扩容），并鉴于严重程度将其标记为需要人工批准 8. **Postmortem Agent** 生成结构化报告，并向知识库添加新的 runbook 条目 ### 实际追踪日志（真实运行输出） ``` [MONITORING] Analyzing metrics for ap-south-1/video-streaming... -> Severity classified: high [ROOT CAUSE] Investigating deployment/software issues... -> Hypothesis: bad_deployment (confidence: 0.95) [CAPACITY] Investigating load/scaling issues... -> Hypothesis: load_spike (confidence: 0.85) [INCIDENT COMMANDER] Evaluating hypotheses (round 0)... !! CONFLICT DETECTED — requesting reconciliation IC question: "Did the v2.3.1 deployment cause the CDN cache hit rate to collapse and trigger the load, or did an independent surge in traffic expose a latent vulnerability in the new deployment?" >> Dispatching reconciliation round 1... [ROOT CAUSE (reconciliation round 1)] Investigating deployment/software issues... -> Hypothesis: bad_deployment (confidence: 0.95) [CAPACITY (reconciliation round 1)] Investigating load/scaling issues... -> Hypothesis: bad_deployment (confidence: 0.95) ← CHANGED from load_spike [INCIDENT COMMANDER] Evaluating hypotheses (round 1)... [IC] Root Cause revision: bad_deployment -> bad_deployment (delta +0.00) [IC] Capacity revision: load_spike -> bad_deployment (confidence +0.10) -> Status: resolved -> Final root cause: v2.3.1 deployment regression in video transcoding pipeline and connection pooling logic caused CDN cache hit rate collapse from 94% to 62%, triggering origin surge. [REMEDIATION] Proposing remediation action... -> Action: Rollback v2.3.1 to v2.3.0 in ap-south-1 -> Requires approval: True -> Status: pending_approval [POSTMORTEM] Generating incident report and updating knowledge base... -> Built index with 5 chunks from 4 runbooks (new entry added) -> Postmortem written, knowledge base updated ``` **证明真正多智能体行为的关键点**：在看到 Root Cause Agent 提供的关于 CDN 缓存命中率崩溃是部署回归的症状而非外部负载异常的证据后，Capacity Agent 将其立场从 `load_spike` (0.85) 修改为了 `bad_deployment` (0.95)。这是真正的立场修正——而非剧本化的结果。 ## 安全与负责任的 AI - **结构化输出校验**：每个 LLM 决策都通过 Pydantic schema 进行解析。如果校验失败，系统会附带错误信息重试一次，然后显式报错——绝不盲目使用无效数据继续执行。 - **安全护栏**：每个智能体提示词都包含安全后缀：禁止捏造证据，在猜测前明确标示为低置信度，将不可逆/高严重性的操作标记为需要批准，输出中禁止包含 PII。 - **Human-in-the-loop**：带有 `requires_approval=True`（高/危重级别严重性或不可逆操作）的修复操作会暂停执行，并需要明确的人工批准。 - **密钥管理**：所有凭证均通过 `.env` 文件（已 gitignored）提供，通过 `pydantic-settings` 加载。所有端点均设有 API key 身份验证中间件。 - **审计追踪**：将每次 LLM 调用（智能体名称、prompt hash、模型、延迟、prompt/completion token）以结构化 JSON 格式记录到 `logs/sentinel.log`——绝不记录密钥或完整的 prompt。 - **指标**：三个层级（工作流 / 智能体 / LLM）的 Prometheus metrics 通过 `GET /metrics` 暴露；预构建的 Grafana 仪表板位于 `observability/sentinel-dashboard.json`。 ## 可观测性（内置） Sentinel 具备生产级的可观测性，分为三个层级，通过 Prometheus exposition 格式在 `GET /metrics` 提供： **工作流级别：** `sentinel_incidents_total`、`sentinel_incidents_by_final_status_total`、`sentinel_incident_duration_seconds`、`sentinel_conflicts_detected_total`、`sentinel_reconciliation_rounds_total`、`sentinel_hypothesis_revisions_total` **智能体级别：** `sentinel_agent_invocations_total{agent,phase}`、`sentinel_agent_latency_seconds{agent}`、`sentinel_agent_iterations{agent}`、`sentinel_agent_tool_calls_total{agent,tool}` **LLM 级别：** `sentinel_llm_calls_total{agent,model,outcome}`、`sentinel_llm_latency_seconds{agent,model}`、`sentinel_llm_tokens_total{agent,model,direction}`、`sentinel_llm_errors_total{agent,error_type}`、`sentinel_llm_rate_limit_backoffs_total{agent}` **在本地启动 Prometheus + Grafana：** ``` uvicorn app.main:app --reload # Sentinel on :8000 cd observability && docker compose up -d # Prometheus → http://localhost:9090 # Grafana → http://localhost:3000 (dashboard 自动配置) ``` ### Agent Trace Viewer UI 内置的单页追踪查看器通过 `GET /`（根 URL）提供服务。它提供： - **场景选择器** — 选择场景并直接从浏览器运行 - **摘要仪表板** — 事件 ID、状态、严重程度、受影响用户、冲突状态、协调轮数、持续时间、智能体数量 - **智能体流程图** — 带有 3D 透视变换的 7 节点图，展示管道拓扑，按智能体角色进行颜色编码，并带有协调循环指示器 - **智能体追踪卡片** — 每个智能体的可展开卡片，显示每个事件：工具调用（带有参数和结果预览）、LLM 迭代（带有 token 计数）、假设（带有置信度条和证据）、冲突检测、IC 决策、修复建议和复盘报告 - **全部展开/收起**控件，以及通过点击从流程图节点导航至追踪卡片的功能 ## 工具访问控制 工具通过受限的内部注册表（`app/tools/registry.py`）进行注册。每个智能体只能访问其指定的工具： | 智能体 | 工具 | |---|---| | Monitoring | `check_metrics` | | Root Cause | `check_deploy_logs`、`retrieve_sop` (RAG) | | Capacity | `check_load_capacity`、`retrieve_sop` (RAG) | | Customer Impact | `estimate_affected_users` | | Remediation | `propose_remediation`、`execute_remediation_mock` | | Incident Commander | 无（逻辑为图路由） | | Postmortem | 无（直接写入知识库） | 该注册表与 MCP 能力授权 1:1 映射——每个智能体的工具列表可以直接迁移到 MCP 服务器，而无需更改智能体逻辑。 ## 生产化路线图 ### MCP 服务器迁移 当前的工具注册表（`registry.py`）通过 Python 字典对每个智能体强制执行最小权限工具访问。在生产环境中，这将替换为完整的 MCP（Model Context Protocol）服务器，其中每个智能体的工具访问权限通过能力 token 授予。当前注册表与 MCP 能力授权之间的 1:1 映射是有意为之的——无需更改智能体逻辑。 ### OpenTelemetry 分布式追踪 为每个事件 ID 添加 OpenTelemetry span 以实现跨服务追踪，针对异常延迟/错误激增添加告警规则，并添加按区域划分的 SLO 仪表板。 ### 状态持久化 目前使用的是以 `incident_id` 为键的内存字典 `dict[str, IncidentState]`。生产环境的部署将使用： - **Redis** 用于热状态（活跃事件），具有基于 TTL 的过期机制 - **PostgreSQL** 用于冷存储（已解决的事件、复盘），具有针对每个事件的行级锁定以支持并发访问 - 事务安全的状态转换，防止多用户场景中的竞态条件 ### 扩展的 HITL 控制 - 基于严重程度和影响范围的基于角色的批准链（L1 NOC → L2 工程 → L3 架构） - 用于批准工作流的 Slack/PagerDuty 集成 - 可配置的自动批准策略，用于在非高峰时段处理低严重性、可逆的操作 ### 额外的智能体 - **Change Management Agent**：在批准回滚之前与变更管理系统进行交叉比对 - **Communication Agent**：管理多渠道客户通知（SMS、电子邮件、应用内），并进行受众细分 - **Compliance Agent**：确保事件响应符合监管要求（SLA 追踪、审计日志记录）

标签：LangGraph, 冲突协调, 多智能体, 检索增强生成, 网络运营中心, 自定义请求头, 运维自动化, 逆向工具