Dafomu96/ai-incident-response
GitHub: Dafomu96/ai-incident-response
基于 LangGraph 的多 Agent 协作系统，通过并行数据采集、RAG 诊断推理和分级人机协同，自动化 IT 生产事件的分类、诊断、处置与复盘。
Stars: 0 | Forks: 0
# AI 事件响应系统
## 目录
1. [动机](#1-motivation)
2. [架构](#2-architecture)
3. [5 个 Agent](#3-the-5-agents)
4. [技术栈](#4-technical-stack)
5. [架构决策记录 (ADRs)](#5-architecture-decision-records-adrs)
6. [评估结果](#6-evaluation-results)
7. [仓库结构](#7-repository-structure)
8. [环境配置](#8-setup)
9. [使用方法](#9-usage)
10. [可观测性](#10-observability)
11. [路线图](#11-roadmap)
## 1. 动机
SRE 团队平均花费 40-60 分钟来识别 P1 事件的根本原因。在这段时间内，生产系统可能会产生数万欧元的损失并影响数千名用户。人工处理流程存在三个结构性问题：
**上下文碎片化。** 日志在 Loki 中，指标在 Prometheus 中，最近的提交在 GitHub 中，而 pod 状态在 Kubernetes 中。值班 SRE 必须在压力下手动关联这些信息源。
**非持久化知识。** Runbook 和历史复盘报告虽然存在，但并没有被系统地查阅。每次事件都从零开始解决，而没有利用积累的知识。
**在缺乏完整上下文的情况下做出高风险决策。** 凌晨 3 点批准回滚的工程师并不总是能获得促成该建议的完整诊断信息。
本系统解决了这三个问题：并行收集上下文，自动查询历史知识库，并在展示高风险决策时提供知情批准所需的所有上下文。
## 2. 架构
### 完整流程
```
Prometheus/PagerDuty Alert
|
v
+-----------------+
| Agent 1 | Groq Llama 3.3 70B -- P1/P2/P3 classification
| Monitor & | Target latency: <500ms
| Triage |
+--------+--------+
| [P1/P2: escalate] ----------- [P3 trivial: auto-resolve]
v
+-----------------+
| Agent 2 | asyncio.gather -- parallel collection
| Data | Loki (logs) + Prometheus (metrics) +
| Collector | GitHub API (commits) + K8s API (pods)
+--------+--------+
|
v
+-----------------+
| Agent 3 | Groq Llama 3.3 70B (dev) / Claude Sonnet (prod)
| Diagnostic | RAG over runbooks + historical postmortems
| Reasoner -----+--[low confidence]--> Agent 2 (retry, wider window)
| (Core) | Chain-of-thought + Pydantic structured output
+--------+--------+
| [confidence >= threshold]
v
+-----------------+
| Agent 4 | Classifies actions by risk (LOW/HIGH)
| Remediation | LOW: auto-executable
| Planner | HIGH: generates HITLRequest for Slack approval
+--------+--------+
|
+----+----+
| |
v v
[HIGH] [LOW / auto]
HITL Auto
Slack --> execution
approval |
+--------+
|
v
+-----------------+
| Agent 5 | Generates structured postmortem
| Postmortem | Ingests into ChromaDB <-- Learning loop
| Writer |
+-----------------+
```
### LangGraph 图属性
**持久化状态。** `IncidentState`（类型化的 TypedDict）通过 checkpointing 在每个节点持久化。如果系统在处理事件期间崩溃，它会从中断的地方准确恢复。
**原生循环。** 如果 Diagnostic Reasoner 确定需要更多数据（`requires_more_data=True`），图会自动返回到 Data Collector 并扩大时间窗口。最多重试 2 次以防止无限循环。
**条件边。** 图中有三个显式的决策点：升级或自动解决（分流后）、重新诊断或制定计划（诊断后）、HITL 或执行（规划后）。
**错误恢复。** 专用的 `error` 节点可捕获异常，将其记录到 LangSmith，并防止图进入不一致的状态。
## 3. 5 个 Agent
### Agent 1 -- 监控与分类 (`agents/monitor_triage.py`)
**角色：** 系统入口点。与告警的第一次接触。
**模型：** Groq Llama 3.3 70B -- 选择它是为了低延迟（<500ms），而不是推理能力。
**职责：** 接收来自 Prometheus 或 PagerDuty 的 `IncidentAlert`，对严重程度进行 P1/P2/P3 分类，提取受影响的组件和时间窗口，决定是否升级到全图流程。
**输出：** `IncidentReport` -- 严重程度、受影响组件、升级标志、分类理由。
### Agent 2 -- 数据收集器 (`agents/data_collector.py`)
**角色：** 调查员。并行收集完整上下文。
**模型：** 无 LLM -- 仅直接通过 tool-calling 调用 API。
**职责：** Loki 日志（过去 N 小时）、Prometheus 指标（错误率、p99 延迟、CPU、内存）、GitHub 提交和 PR、Kubernetes pod 状态。
**并行机制：** `asyncio.gather` -- 同时查询所有 4 个来源。当未配置 URL/token 时，所有工具都有自动的 mock 回退机制。
### Agent 3 -- 诊断推理器 (`agents/diagnostic_reasoner.py`)
**角色：** 项目的核心。系统中最为复杂的 agent。
**模型：** Groq Llama 3.3 70B (开发) / Claude Sonnet (生产)。
**职责：** 基于收集到的完整上下文进行推理，查询包含 runbook 和历史复盘报告的 RAG 知识库，生成按概率排序并附带证据的根本原因假设，在置信度较低时设置 `requires_more_data=True`。
**输出：** 包含假设、`overall_confidence`、完整 `reasoning_chain` 的 `DiagnosisResult`。
### Agent 4 -- 补救规划器 (`agents/remediation_planner.py`)
**角色：** 将诊断转化为具体行动。
**模型：** Groq Llama 3.3 70B (开发) / Claude Sonnet (生产)。
**权限矩阵：**
- **LOW (可自动执行)：** 重启 pod、清理缓存、重载配置、扩缩容副本数
- **HIGH (需要批准)：** 回滚部署、删除数据、修改防火墙规则
**输出：** 带有分类操作的 `RemediationPlan` + 用于高风险操作的 `HITLRequest`。
### Agent 5 -- 总结报告编写器 (`agents/postmortem_writer.py`)
**角色：** 闭环。生成复盘报告并反馈到系统中。
**模型：** Groq Llama 3.3 70B (开发) / Claude Sonnet (生产)。
**关键区别：** 将生成的复盘报告导入 ChromaDB，以便未来的诊断能从积累的知识中受益。形成闭环学习。
**输出：** `PostmortemDraft` + 自动导入 RAG 知识库。
## 4. 技术栈
### Agent 编排
| 组件 | 技术 | 决策原因 |
|---|---|---|
| Agent 框架 | LangGraph | 循环状态、checkpointing、条件边 |
| 图状态 | Typed TypedDict | 静态类型，兼容 mypy |
| Checkpointing (开发环境) | MemorySaver | 内存中，无依赖 |
| Checkpointing (生产环境) | SqliteSaver | 跨重启持久化 |
### LLM 模型
| Agent | 模型 (开发) | 模型 (生产) | 标准 |
|---|---|---|---|
| Agent 1 (Triage) | Groq Llama 3.3 70B | Groq Llama 3.3 70B | 延迟 <500ms |
| Agent 3/4/5 | Groq Llama 3.3 70B | Claude Sonnet | 深度推理 |
| RAG 上下文化 | Groq Llama 3.3 70B | Claude Haiku | 每个分块的最低成本 |
| 全局回退 | GPT-4o | GPT-4o | 弹性与容错 |
### RAG -- 知识库
| 组件 | 技术 | 决策原因 |
|---|---|---|
| 向量存储 | ChromaDB | 本地持久化，易于设置 |
| Embeddings | sentence-transformers (all-MiniLM-L6-v2) | 开源，无单次调用成本 |
| Chunking | RecursiveCharacterTextSplitter | 512 tokens，50 重叠 |
| 上下文化 | Contextual Retrieval (Anthropic) | 为每个分块增加 50-100 个上下文 token |
| 重排序 (Reranking) | Cohere Rerank v3 | 提升检索精度（可选） |
### Schema 与验证
全部使用 **Pydantic v2** 实现 -- 严格验证、原生 JSON Schema、解析错误重试逻辑：`IncidentAlert`、`IncidentReport`、`DiagnosisResult`、`RemediationPlan`、`HITLRequest`、`PostmortemDraft`。
### 基础设施
| 组件 | 技术 |
|---|---|
| API 后端 | FastAPI + WebSockets |
| 容器化 | Docker + docker-compose |
| CI/CD | GitHub Actions |
| 可观测性 | LangSmith |
| HITL | 带有交互按钮的 Slack bot |
## 5. 架构决策记录 (ADRs)
### ADR-001 -- 选择 LangGraph 而非 crewAI
**背景：** 评估了 LangGraph、crewAI 和 AutoGen 作为编排框架。
**决策：** LangGraph。
**原因：** 事件具有复杂的、非线性的状态。如果诊断置信度较低，Diagnostic Reasoner 可能需要返回到 Data Collector。crewAI 针对具有固定角色的线性 pipeline 进行了优化，且原生不支持条件循环。LangGraph 恰好提供了该系统所需的模式：带有类型化状态的循环图、用于故障恢复的 checkpointing，以及用于实现显式、可测试决策逻辑的条件边。
**权衡：** 代码比 crewAI 更冗长，学习曲线也更陡峭。为了换取细粒度的流程控制，这是可接受的。
### ADR-002 -- 三个基于特定任务标准的模型
**背景：** 可以对所有 agent 使用单个模型。
**决策：** 根据任务类型使用不同的模型。
**原因：** Agent 1 需要低于 500ms 的延迟 -- 搭载 Llama 3.3 70B 的 Groq 响应时间约为 300ms。Agent 3、4 和 5 需要深度推理和可靠的结构化输出 -- 生产环境中使用 Claude Sonnet。对于会生成数百次小规模调用的 RAG 分块上下文化，使用 Claude Haiku。GPT-4o 作为全局回退方案。
**权衡：** 运维复杂度更高（需要多个 API key）。但通过针对每个任务进行的成本-延迟-质量优化得以抵消。
### ADR-003 -- 选择 Contextual Retrieval 而非传统 RAG
**背景：** 最初实现的是传统 RAG（分块 -> embedding -> 检索）。
**决策：** Contextual Retrieval（Anthropic，2024 年 9 月）。
**原因：** 当被切分为 512 token 的分块时，运维 runbook 会失去原有的语义。Contextual Retrieval 在进行 embedding 之前，会为每个分块添加 50-100 个由 LLM 生成的上下文 token。根据 Anthropic 的基准测试，与传统 RAG 相比，这能将检索错误减少多达 67%。
**权衡：** 额外的导入成本（每个文档一次性产生，而非每次检索产生）。但通过提升的诊断精度得以抵消。
### ADR-004 -- 基于操作风险而非事件严重程度进行 HITL
**背景：** 是否对所有事件还是仅对部分事件实施 HITL。
**决策：** 基于操作类型的权限矩阵，独立于事件严重程度。
**原因：** 严重程度描述的是事件的影响。操作风险描述的是修复措施的影响。它们是正交维度。即使是 P1 事件，执行可逆操作（重启 pod）也可安全地自动执行。即使是 P2 事件，破坏性操作（回滚部署）也需要人工批准。
**权衡：** Agent 4 的 LOW/HIGH 分类在极端情况下可能出错。所有决策的不可变审计日志允许识别并纠正这些情况。
### ADR-005 -- 自定义评估而非 RAGAS
**背景：** RAGAS 是 RAG 系统评估的标准框架。
**决策：** 使用 LangSmith 和自定义指标直接针对基准真值进行评估。
**原因：** RAGAS 在 Python 3.11 中与 LangGraph 0.2+ 存在依赖冲突，并且每次评估都会增加 LLM 成本。使用包含 8 个带有真实根本原因的历史事件数据集进行直接评估，比抽象的忠实度指标更具相关性。
## 6. 评估结果
基于具有真实基准真值（根本原因、严重程度、正确操作）的 **8 个历史事件**进行的评估。模型：Groq Llama 3.3 70B（开发环境）。
| 指标 | 结果 | 生产环境目标 |
|---|---|---|
| 严重程度准确率 | 62% | >85% |
| Top-1 诊断准确率 | 38% | >70% |
| Top-3 诊断准确率 | 62% | >90% |
| 平均关键词得分 | 23% | >50% |
| 平均置信度 | 84% | -- |
| HITL 触发率 | 100% | -- |
| 复盘报告生成率 | 100% | -- |
| 平均诊断尝试次数 | 1.0 | -- |
| 诊断时间 (平均) | ~7s | <30s |
**分析：** 该系统能够正确诊断在日志和提交中具有明确信号的事件（DB 连接池、N+1 查询、Elasticsearch）。在处理缺乏代码信号的基础设施事件时（SSL 过期、磁盘已满）则显得吃力。开发环境与生产环境之间的差距会随着使用 Claude Sonnet 而缩小，因为后者在处理模糊信号方面具有更好的推理能力。
## 7. 仓库结构
```
ai-incident-response/
|-- agents/ # The 5 LangGraph agents
| |-- monitor_triage.py # Agent 1: P1/P2/P3 classification with Groq
| |-- data_collector.py # Agent 2: parallel collection with asyncio
| |-- diagnostic_reasoner.py # Agent 3: RAG + chain-of-thought (core)
| |-- remediation_planner.py # Agent 4: remediation plan + HITL trigger
| `-- postmortem_writer.py # Agent 5: postmortem + RAG ingestion
|
|-- graph/ # LangGraph orchestration
| |-- state.py # IncidentState -- typed TypedDict
| |-- workflow.py # StateGraph + conditional edges
| `-- checkpointer.py # MemorySaver (dev) / SqliteSaver (prod)
|
|-- tools/ # Tool-calling to external APIs
| |-- prometheus.py # Historical metrics (service-specific mock)
| |-- loki.py # Logs for last N hours (service-specific mock)
| |-- github_api.py # Recent commits and PRs (service-specific mock)
| |-- kubernetes_api.py # Pod status (with mock)
| `-- slack_hitl.py # Slack bot HITL with Approve/Reject buttons
|
|-- rag/ # RAG pipeline with Contextual Retrieval
| |-- ingestion.py # Chunking + contextualization + embedding
| |-- retriever.py # Dense search + optional Cohere reranker
| |-- chroma_store.py # ChromaDB singleton
| `-- seed_runbooks.py # 5 example runbooks for initial ingestion
|
|-- schemas/ # Pydantic v2 -- typed structured outputs
| |-- incident.py # IncidentAlert + IncidentReport
| |-- diagnosis.py # DiagnosisResult + RootCauseHypothesis
| |-- remediation.py # RemediationPlan + HITLRequest
| `-- postmortem.py # PostmortemDraft + to_rag_document()
|
|-- evals/ # Evaluation with LangSmith + ground truth
| |-- datasets/
| | `-- historical_incidents.json # 8 incidents with real root causes
| |-- run_evals.py # Evaluation runner
| |-- metrics.py # Top-1/3 accuracy, keyword score, severity accuracy
| `-- results_latest.json # Latest evaluation results
|
|-- api/ # FastAPI backend
| `-- main.py # REST + WebSocket + /slack/actions callback
|
|-- frontend/ # React + Vite dashboard
| `-- src/App.jsx # Live pipeline log, HITL queue, eval metrics
|
|-- infra/ # Infrastructure
| |-- Dockerfile
| `-- docker-compose.yml
|
|-- .github/workflows/
| `-- ci.yml # Tests + lint + Docker build on each push
|
|-- docs/ # Architecture Decision Records
| |-- ADR-001-langgraph.md
| |-- ADR-002-models.md
| |-- ADR-003-contextual-retrieval.md
| |-- ADR-004-hitl.md
| `-- ADR-005-evaluation.md
|
|-- tests/ # 71 tests -- schemas, routing, tools, HITL, API, integration
| |-- test_schemas.py
| |-- test_state.py
| |-- test_tools_mock.py
| |-- test_hitl.py
| `-- test_data_collector.py
|
|-- demo.py # Single-command demo script
|-- run_incident.py # End-to-end test script
|-- pyproject.toml
|-- .env.example
`-- README.md
```
## 8. 环境配置
### 依赖要求
- Python 3.11+
- Docker Desktop（用于容器化执行）
- Node.js 18+（用于前端 dashboard）
### 安装
```
# 1. 克隆仓库
git clone https://github.com/Dafomu96/ai-incident-response.git
cd ai-incident-response
# 2. 虚拟环境与依赖
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pip install langchain-text-splitters python-multipart
# 3. 环境变量
cp .env.example .env
# 编辑 .env -- 最低要求：GROQ_API_KEY
# 4. 将 runbooks 导入 ChromaDB
python -m rag.seed_runbooks
# 5. 运行 demo
python demo.py
```
### 开发环境的最少环境变量
```
GROQ_API_KEY=gsk_... # Required -- all agents
LANGSMITH_API_KEY=lsv2_pt_... # Recommended -- observability
LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://eu.api.smith.langchain.com
LANGCHAIN_PROJECT=ai-incident-response
SLACK_BOT_TOKEN=xoxb-... # Optional -- real HITL
SLACK_HITL_CHANNEL=#incident-approvals
```
### Docker
标签：IT事件响应, LangGraph, PyRIT, 多智能体系统, 子域名突变, 自动化运维, 自定义请求头, 请求拦截, 逆向工具