nishujayaraj/MultiAgent-SRE
GitHub: nishujayaraj/MultiAgent-SRE
基于LangGraph多Agent编排的SRE事件自动诊断系统，通过并行Agent协作将人工分诊过程从分钟级压缩到秒级。
Stars: 0 | Forks: 0
# MultiAgent-SRE
## 它解决的问题
想象一下这个场景：凌晨 3 点，PagerDuty 把你吵醒。你打开了五个标签页 —— Datadog、Kubernetes dashboard、Jira、Confluence、Slack —— 然后花接下来的 15 分钟仅仅是为了搞清楚*发生了什么*。是数据库宕机了还是仅仅变慢了？哪些服务受到了影响？上次发生这种情况时是怎么修复的？等你把这些线索串联起来时，真实用户早已经体验不佳了。
事实是，实际的修复通常只需要 5 分钟。*诊断*才是耗费时间的事情。
**MultiAgent-SRE 将诊断过程自动化了。** 警报触发的瞬间，一个 AI agent 团队就会立即行动起来：一个读取你的日志，一个搜索你的 runbook 库，一个评估受影响的用户数量。它们同时工作，分享各自的发现，并为你呈上一份完整的事故简报。根因已查明，修复步骤已按风险分级排列，Jira 工单也已起草完毕。你到达时迎接你的是一个待决策的方案，而不是一个空白屏幕。
## 工作原理
以下是警报在系统中经历的旅程：
1. **警报传入** → Supervisor agent 读取警报，对事故类型进行分类，并设定严重级别
2. **三个 agent 并行工作** → Log Analyzer 深入排查原始日志，Runbook RAG 使用语义搜索检索你的 runbook 库，Impact Assessor 评估受影响的用户和服务
3. **综合根因** → 一个专门的 agent 获取所有三个输出，并构建一个带有置信度分数的因果链
4. **规划修复方案** → 另一个 agent 生成 3-5 个优先排序的步骤，包含真实命令（kubectl、psql 等）和风险级别
5. **人工决策点** → 如果事故是 CRITICAL 级别，或者 AI 不够自信，它会暂停并询问你：*执行还是上报？*
6. **创建工单** → 自动生成一张包含完整事故报告的结构化 Jira 工单
从警报到简报的总时间：**60 秒以内。**
## 架构
该流水线是一个 LangGraph `StateGraph` —— 不是顺序执行的链，而是一个具有并行分支和条件路由的真实图。
```
+------------------+
| SUPERVISOR |
| classifies alert|
| sets severity |
+--------+---------+
|
+-------------------+-------------------+
| | |
v v v
+---------------+ +--------------+ +------------------+
| LOG ANALYZER | | RUNBOOK RAG | | IMPACT ASSESSOR |
| error_patterns| | ChromaDB | | affected_services|
| anomalies | | vector | | users_impacted |
| log_summary | | search | | blast_radius |
+-------+-------+ +------+-------+ +---------+--------+
| | |
+------------------+---------------------+
(all 3 merge here)
v
+------------------+
| ROOT CAUSE |
| causal_chain |
| confidence_score|
+--------+---------+
|
v
+---------------------+
| REMEDIATION PLANNER |
| 3-5 ranked steps |
| risk + time per step|
+---------+-----------+
|
+----------------+----------------+
| CRITICAL severity |
| OR confidence < 70% | (otherwise auto)
v v
+------------------+ +------------------+
| HUMAN CHECKPOINT | | TICKET CREATOR |
| execute/escalate +------------>| Jira + summary |
+------------------+ +---------+--------+
|
v
[END]
```
中间的三个 agent（Log Analyzer、Runbook RAG、Impact Assessor）**并行**运行，LangGraph 在 Supervisor 之后扇出，并在 Root Cause 之前扇入。这将诊断时间从约 15 秒的顺序执行缩短到了约 5 秒。
## Agents
每个 agent 都有自己的职责。它从共享状态中读取所需内容，完成其工作，然后将其输出写回。
| Agent | 功能 | 使用 LLM? | 关键输出 |
|---|---|---|---|
| **Supervisor** | 读取警报，选择事故类型，设定严重性 | 是 | `classification`, `severity` |
| **Log Analyzer** | 从原始日志中查找错误模式和异常 | 是 | `error_patterns`, `anomalies`, `log_summary` |
| **Runbook RAG** | 对你的 runbook 库进行语义搜索 (ChromaDB) | 否 | `relevant_runbooks` |
| **Impact Assessor** | 评估受影响的服务和用户数量 | 是 | `blast_radius`, `estimated_users_impacted` |
| **Root Cause** | 将所有信息综合成因果链 + 置信度分数 | 是 | `root_ause`, `confidence_score`, `causal_chain` |
| **Remediation Planner** | 生成排序后的步骤，包含真实命令和风险级别 | 是 | `remediation_steps`, `recommended_action` |
| **Human Checkpoint** | 询问值班工程师决定：执行还是上报 | 否 (stdin) | `human_decision` |
| **Ticket Creator** | 编写结构化的 Jira 事故工单 | 是 | `ticket_id`, `resolution_summary` |
## 技术栈
| 类别 | 工具 | 选择原因 |
|---|---|---|
| LLM | Claude Haiku 4.5 (`claude-haiku-4-5-20251001`) | 快速且成本低 —— 在事故中分秒必争，这点非常重要 |
| Agent 编排 | LangGraph `StateGraph` | 开箱即用地支持并行执行和条件路由 |
| LLM 客户端 | `langchain-anthropic` | 简洁的消息格式化，易于替换模型 |
| Runbook 搜索 | ChromaDB + `all-MiniLM-L6-v2` | 本地运行，无需外部服务，运行期间持久化 |
| 可观测性 | Langfuse | 精确查看每个 agent 接收了什么、返回了什么以及耗时多少 |
| 状态 | Python `TypedDict` + `Annotated` | 类型安全，能在运行时捕获错误，避免引发隐性 bug |
| 配置 | `python-dotenv` | 密钥存放在 `.env` 中，绝不硬编码 |
## 快速开始
你只需要一个 Anthropic API 密钥即可运行。Langfuse 是可选的。
```
# 1. Clone the repo
git clone https://github.com/nishujayaraj/MultiAgent-SRE.git
cd MultiAgent-SRE
# 2. 创建 virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 3. 安装依赖
pip install -r requirements.txt
# 4. 设置你的 API key
cp .env.example .env
# 打开 .env 并添加你的 ANTHROPIC_API_KEY
# Langfuse keys 是可选的 —— 没有它们系统也能正常运行
# 5. 运行它
python main.py
```
首次运行时，ChromaDB 将嵌入 8 个 runbook 文件（大约需要 5 秒）。此后的每次运行都会立即加载已保存的集合。
## 试一试 —— 三种内置场景
当你运行 `python main.py` 时，你可以选择三种预置事故之一：
```
[1] INC-001 — DB connection pool pressure
payments-service | prod | HIGH severity | no human checkpoint
[2] INC-002 — OOMKilled memory leak, CrashLoopBackOff
recommendation-service | prod | CRITICAL | ⚠ asks for your decision
[3] INC-003 — Sustained high CPU at 94% for 8 minutes
data-pipeline | staging | MEDIUM severity | no human checkpoint
```
场景 2 是最有趣的一个，它会触发 human checkpoint，向你展示完整的简报，并等待你输入 `execute` 或 `escalate`。
### 示例输出 (场景 1)
```
[SUPERVISOR] classification=db_connection | severity=high
[IMPACT ASSESSOR] ~45,000 users impacted | 4 service(s) affected
[RUNBOOK RAG] Matched: Db Connection Exhaustion, High Cpu, Redis Timeout
[LOG ANALYZER] 8 error patterns, 5 anomalies found
[ROOT CAUSE] confidence=78% | auto path (no human needed)
[REMEDIATION] 5 steps planned
[TICKET] Created INC-001-1778003021
╔════════════════════════════════════════════════════════════════╗
║ INCIDENT REPORT — MultiAgent SRE ║
╚════════════════════════════════════════════════════════════════╝
Ticket ID : INC-001-1778003021
Service : payments-service (prod)
Severity : HIGH
Classification : db_connection
Human Decision : N/A — AUTO PATH
Root Cause : HikariPool exhausted due to idle-in-transaction
connections piling up after a traffic spike.
Recommended : SELECT pg_terminate_backend(pid) FROM
pg_stat_activity WHERE state = 'idle in transaction'
AND now() - query_start > interval '2 minutes';
```
## 性能基准
这些数据来自对三个内置场景的端到端运行。每次耗时为 3 次运行的平均值；置信度和检索分数是确定的 (temperature=0)。
### 端到端流水线时间
每个场景运行 6-7 次 LLM 调用（supervisor → 3 个并行 agent → root cause → remediation → ticket）。三个并行 agent 同时运行，将中间阶段从约 15 秒的顺序执行缩短到了约 5 秒。
| 场景 | 服务 | 严重性 | 平均耗时 (3次运行) |
|---|---|---|---|
| INC-001 — DB 连接池 | payments-service | HIGH | **28.7s** |
| INC-002 — OOMKilled / CrashLoopBackOff | recommendation-service | CRITICAL | **27.9s** |
| INC-003 — 持续高 CPU | data-pipeline | MEDIUM | **33.5s** |
从输入警报到生成 Jira 工单的总时间：在所有场景中均**低于 35 秒**。
### 根因置信度分数
Root cause agent 在 0-1 的范围内对其自身的确定性进行评分。任何低于 70% 的情况都会触发 human checkpoint，无论严重性如何。
| 场景 | 根因 (摘要) | 置信度 | 人工批准? | 原因 |
|---|---|---|---|---|
| INC-001 | Idle-in-transaction 连接耗尽 HikariPool | **82%** | 否 | ≥70% 且严重性不为 CRITICAL |
| INC-002 | 无界缓存无驱逐策略 → 重启时 OOM | **95%** | **是** | CRITICAL 严重性覆盖 |
| INC-003 | O(n²) JSON 反序列化导致 CPU 饱和 | **92%** | 否 | ≥70% 且严重性不为 CRITICAL |
INC-002 触发了 human checkpoint 并不是因为置信度低 —— 它是最高的 95% —— 而是因为 CRITICAL 级别始终需要人工决策。
### Runbook RAG 检索准确性
使用涵盖所有主要事故类型的 5 条警报信息进行了测试。RAG 返回前 3 个结果；准确性以排名第 1 的结果进行衡量。
| 指标 | 结果 |
|---|---|
| Top-1 准确率 | **80%** (4 / 5) |
| Top-3 召回率 | **100%** (5 / 5) |
那个误判：一个 OOMKilled + CrashLoopBackOff 警报在排名 1 检索到了 *Pod Crashloop*（相似度 0.69），而不是 *Memory Leak*（相似度略低）。正确的 runbook 仍然排在第 2 位 —— 因此它成功进入了 LLM 上下文，并且该场景的根因置信度达到了 95%。Top-3 召回率 100% 意味着，即使排名第 1 有误，相关的 runbook 也总是能到达推理 agent 那里。
| 警报 | 预期 | 检索结果 (排名 1) | 相似度 | 是否正确? |
|---|---|---|---|---|
| HikariPool exhausted, connection timeout | Db Connection Exhaustion | Db Connection Exhaustion | 0.655 | ✓ |
| OOMKilled, CrashLoopBackOff, Java heap | Memory Leak | Pod Crashloop | 0.687 | ✗ |
| CPU at 94%, load avg 15.2 | High Cpu | High Cpu | 0.497 | ✓ |
| Redis NOAUTH errors, cache hit rate 12% | Redis Timeout | Redis Timeout | 0.668 | ✓ |
| Deployment stuck, ImagePullBackOff | Deployment Failure | Deployment Failure | 0.594 | ✓ |
## 为什么使用 LangGraph 而不仅仅是脚本？
你可以用普通的 Python 将这些 agent 串联起来，调用一个函数，将结果传递给下一个，就这样。但是这个项目需要三样脚本法轻易提供的东西：
**并行执行。** 日志分析、runbook 搜索和影响评估彼此毫无依赖，没有理由一个接一个地运行。LangGraph 在 Supervisor 之后将它们扇出，并等待全部三个完成后才继续。如果使用脚本，你必须自己管理 `asyncio` 或线程。
**条件路由。** Human checkpoint 仅在特定条件下触发（CRITICAL 级别或低置信度）。在 LangGraph 中，这只需一次 `add_conditional_edges` 调用。而在脚本中，随着系统增长，这会变成纠缠不清的 `if/else` 分支。
**安全的并行状态合并。** 所有三个并行 agent 都将消息追加到同一个共享列表中。如果没有 reducer，后写入的 agent 会默默地覆盖其他 agent 的结果。LangGraph 的 `Annotated[List[str], operator.add]` 注解告诉运行时进行拼接，而不需要任何协调代码。
**可见性。** 图是显式声明的：节点、边、条件。你可以一目了然地看清整个流水线，只需添加一个节点和两条边即可引入新 agent，并且可以独立测试任何 agent。
## 项目结构
```
MultiAgent-SRE/
├── src/
│ ├── agents/
│ │ ├── supervisor.py # Classifies alert, sets severity
│ │ ├── log_analyzer.py # Extracts error patterns from logs
│ │ ├── runbook_rag.py # Searches runbooks via ChromaDB
│ │ ├── impact_assessor.py # Estimates blast radius + user impact
│ │ ├── root_cause.py # Builds causal chain + confidence score
│ │ ├── remediation_planner.py # Generates ranked remediation steps
│ │ └── ticket_creator.py # Writes the Jira incident ticket
│ ├── state/
│ │ └── incident_state.py # Shared TypedDict state + Enums
│ ├── tools/
│ │ ├── mock_tools.py # Stub tools: kubectl, Jira, PagerDuty
│ │ ├── runbook_loader.py # Embeds runbooks into ChromaDB
│ │ └── observability.py # Langfuse trace/span wrappers
│ └── data/runbooks/ # 8 realistic SRE runbook .txt files
├── main.py # Graph definition + scenario runner
├── requirements.txt
├── .env.example
└── README.md
```
## 作者
由 **Nischitha S Jayaraja** 构建
[LinkedIn](https://www.linkedin.com/in/nischithasjayaraja/) · [GitHub](https://github.com/nishujayaraj)
标签：AIOps, API集成, Datadog, DevSecOps, DLL 劫持, IT运维, Jira集成, kubectl, LangChain, LangGraph, LLM, On-call自动化, PagerDuty, PyRIT, RAG, Slack集成, Socks5代理, SRE, Unmanaged PE, 上游代理, 人机协同, 偏差过滤, 可观测性, 告警分类, 告警自动化, 因果链分析, 多智能体系统, 大语言模型, 故障自愈, 故障诊断, 智能运维, 根因分析, 检索增强生成, 模块化设计, 站点可靠性工程, 自动化修复, 轻量级, 运维自动化, 逆向工具