shjawale/SRE-Incident-Response-Agent
GitHub: shjawale/SRE-Incident-Response-Agent
基于多 agent 架构的 SRE 事件响应自动化系统，通过人类在环监督机制安全地编排事件分诊、修复和复盘全流程。
Stars: 1 | Forks: 0
# SRE 事件响应 Agent
该系统是一个使用 Google Agent Development Kit (ADK) 构建的 agentic workflow。它通过多 agent 层级结构，实现 SRE 事件管理的自动化，用于研究、分诊、修复和报告 DevOps 事件。复杂的推理任务由 mistral-nemo:12b 模型驱动。
## 概述
该项目实现了端到端的事件响应 pipeline 自动化。RootAgent 充当中央 orchestrator，根据事件状态将用户警报动态路由到专门的 sub-agent。
与 ADK Web 集成提供了一个图形化界面，用于实时监控和 human-in-the-loop (HITL) 监督，允许可视化 agent 的推理路径、监控 sub-agent 交接以及手动批准修复步骤。
### 核心组件
* 编排：使用 Agent 类的分层路由模型。
* LLM：mistral-nemo:12b 通过 LiteLlm 为复杂的分诊、runbook 生成和修复逻辑提供支持。
## 架构与工作流
该系统实现了一个由中央 RootAgent 编排的确定性、顺序化的事件响应架构。RootAgent 专门作为事件指挥官，在执行顺序、安全约束和审计日志记录的同时协调专门的 agent。它不直接进行技术分析。
### 事件生命周期
1. **初始化与范围界定**
操作员手动向 RootAgent 提供 telemetry、日志和其他事件信息。如果缺少数据，系统将提示操作员提供所需的指标。所有操作都会记录在事件时间线中。
2. **分诊**
控制权被委托给 TriageAgent，负责分析日志、stack trace 和历史事件。系统会明确识别数据缺口，并生成简明的分诊报告。
3. **生成 Runbook**
基于分诊结果，系统将生成一份供工程团队使用的内部缓解 runbook。
4. **修复**
RemediationAgent 会提出纠正措施并按风险对其进行分类。低风险操作可自动执行，而高风险或破坏性操作则需要人工批准。执行操作后的验证是强制性的。
5. **验证与关闭**
在宣布事件解决之前，会验证系统稳定性。针对关键状态变化向利益相关者发出通知。
6. **事件后复盘与归档**
编写并归档一份免责的事件后报告，从而正式结束事件生命周期。
### 架构原则
* 职责分离：每个 agent 执行单一、明确的功能。
* 严格排序：事件阶段按固定、强制的顺序执行。
* 操作透明：所有操作均会被记录，以供追踪和审查。
* 人类权威：对生产环境变更的最终控制权仍归属于操作员。
## 事件流转示例
这些示例说明了由 SRE 事件响应 Agent 处理的典型事件生命周期，展示了 agent 委托、human-in-the-loop 检查点和报告机制。
### 流程 1：低风险事件（自动修复）
1. **初始化**：操作员向 RootAgent 提供日志、系统指标和事件描述。
2. **分诊**：TriageAgent 分析数据并识别出配置错误的缓存。
3. **知识库**：KnowledgeAgent 查询 MCP 数据库，以查找类似的历史事件和已知的修复方案。
4. **生成 Runbook**：RunbookAgent 生成一份建议重置缓存的缓解 runbook。
5. **持久化**：PersistenceAgent 生成唯一的事件 ID，并将所有新创建的 runbook 保存回 SQL 数据库。
6. **修复**：
* 操作被归类为低风险 → 自动批准。
* RemediationAgent 自动重置缓存。
7. **验证**：系统指标确认延迟已恢复正常。
8. **关闭**：事件被标记为已解决；事后复盘报告已归档。
关键点：无需人工批准；时间线已完全记录以供审计。
### 流程 2：高风险事件（需要 Human-in-the-Loop）
1. **初始化**：操作员报告错误率升高并向 RootAgent 提供日志。
2. **分诊**：TriageAgent 将配置错误的数据库故障转移确定为根本原因。
3. **知识库**：KnowledgeAgent 查询内部文档和过往事件日志，以识别现有的 runbook 或类似的历史故障模式。
4. **生成 Runbook**：RunbookAgent 生成一份包含高风险操作（例如手动故障转移）的缓解 runbook。
5. **持久化**：PersistenceAgent 将新生成或修改的 runbook 连同唯一的事件 ID 和清晰的标题保存到数据库中，以供将来参考。
6. **修复**：
* 高风险操作 → 需要操作员批准。
* RemediationAgent 提交包含理由和风险评估的批准请求。
* 操作员审查并批准执行。
7. **执行**：执行操作；agent 验证数据库完整性。
8. **验证与关闭**：确认稳定性，通知利益相关者，编写事后复盘报告。
关键点：HITL 确保了操作安全；所有决策均已被记录以符合合规要求。
## Agent 角色
| Agent | 用途
------------------|:---------------------
| TriageAgent | 分析事件数据，识别核心问题，并标记数据缺口。
| Knowledge Agent | 查询 MCP Runbook 数据库以获取历史修复方案。
| RunbookAgent | 生成内部建议的 runbook 供工程团队审查。
| Persistence Agent | 确保新的 runbook 保存到数据库中以供将来使用。
| RemediationAgent | 提出修复方案和操作，区分自动任务和手动回滚。
| PostmortemAgent | 编写最终的内部事件后报告和根本原因分析。
| StatusUpdateAgent | 为内部团队和外部利益相关者格式化状态更新。
## Human-in-the-Loop 安全性
该系统强制要求对任何可能实质性影响服务可用性或基础设施状态的操作进行人工授权。明确禁止自主执行高风险操作。
### 审批控制
在执行之前，RemediationAgent 必须调用包含以下内容的审批请求：
* 拟定的操作
* 技术和运营上的理由
* 带有时间戳的批准记录
### 执行保证
* 审批挂起时，agent 的执行将被暂停。
* 从技术上讲，agent 无法进行自我批准。
* 操作员的决定将按如下方式强制执行：
* 批准通过 → 继续执行。
* 批准拒绝 → 修复立即停止，并生成最终报告。
在审批未解决期间，不会采取任何进一步行动。
Human-in-the-Loop 设计实现了受控自动化，同时保留了生产 SRE 操作所需的可靠性和治理标准。
## Model Context Protocol Runbook 服务器
某些 agent 利用专用的 Model Context Protocol (MCP) 服务器来弥合 LLM 与 runbook 数据库之间的差距。这允许进行标准化、安全且上下文丰富的工具执行。
### 知识检索与持久化
* ```search_runbooks```：跨历史事件记录执行语义搜索，以根据当前的分诊报告找到最相关的过往解决方案。
* ```save_runbook```：如果没有现有的 runbook 与当前事件匹配，则自动持久化新生成的缓解计划。
* 标准化接口：使用统一的协议与 SQLite 后端进行交互，确保一致的数据格式并降低 SQL injection 的风险。
### 配置与工具集
orchestrator 通过 ```StdioConnectionParams``` 连接到服务器。请确保 ```RUNBOOK_MCP_SERVER``` 路径指向您环境中的正确脚本：
```
McpToolset(
connection_params=StdioConnectionParams(
server_params=StdioServerParameters(
command="python3",
args=[RUNBOOK_MCP_SERVER] # should point to tools/runbook_mcp_server.py
)
),
tool_filter=["save_runbook"]
)
```
### 潜在扩展
* 跨服务索引：使用兼容 MCP 的连接器扩展服务器，以跨多个 git 仓库或 Confluence 空间对 runbook 进行索引。
* 向量搜索：将向量数据库（例如 ChromaDB 或 Pinecone）集成到 MCP 服务器中，以实现高级的基于 RAG 的相似性匹配。
* Schema 强制校验：向 MCP 工具添加严格的 Pydantic 验证，以确保所有保存的 runbook 遵循强制的“症状/修复/验证”结构。
## Agent 治理与安全
该 orchestrator 遵循严格的 SRE “Human-in-the-Loop” (HITL) 原则，以防止失控的自动化并确保无责备问责制。
### 已实施的护栏
* 强制审批门禁：高风险工具（例如 execute_infrastructure_action）被程序化锁定。agent 必须在执行前通过 ToolContext 接收已批准的 payload。
* 状态感知终止：如果人工操作员拒绝请求，RemediationAgent 在逻辑上受限于立即停止所有 workflow，以防止系统偏移。
* 不可变的审计追踪：每一个 agent 决策和人工干预都会被追加到 incident_timeline.txt 中，确保为 Postmortem 提供不可抵赖的日志。
### 潜在扩展
* RBAC 集成：将 request_human_approval 连接到 Identity Provider (IDP)，以将审批权限限制为当前的 On-Call Lead。
* Policy-as-Code：集成 Open Policy Agent (OPA) 以定义“禁飞区”（例如“在流量高峰期阻止重启”），以便 agent 在提示人类之前进行检查。
* 脱敏层：添加 middleware 工具，在日志被 StatusUpdateAgent 处理之前剥离 PII 或机密信息。
## 配置与安装
前置条件
* Python 3.10+
* Ollama：可访问 mistral-nemo:12b 模型（或您选择的模型）。
* LiteLLM：初始化 LLM 实例，允许您与模型进行交互。
* MCP 服务器：提供一个标准化接口，供 agent 查询并将 runbook 持久化到 SQLite 数据库中。
* Google 账号（可选）：仅当您稍后选择将 agent 部署到 Google Cloud 服务（如 Vertex AI Agent Engine）时才需要。使用 Ollama 模型进行本地开发不需要此设置。
### 设置
1. 克隆仓库：
git clone https://github.com/shjawale/SRE-Incident-Response-Agent.git
cd sre-incident-agent
2. 安装 Ollama 和 Mistral 模型：
从官方网站下载并安装 Ollama https://ollama.com/download/linux。
打开终端或命令提示符，并运行以下命令以下载 mistral 模型：
ollama pull mistral-nemo:12b
3. 创建并激活虚拟环境：
虚拟环境可确保 ADK 和 LiteLLM 依赖项不会与全局 Python 安装发生冲突。
# 创建环境
python -m venv venv
# 激活它
.\venv\Scripts\activate (Windows)
source venv/bin/activate (macOS/Linux)
4. 安装依赖项：
pip install google-adk litellm httpx python-dotenv
5. 配置环境变量：
在根目录中创建一个 .env 文件并添加凭证。有关所需格式，请参阅 .env.example：
OPENAI_API_KEY=
## 用法
1. 在代码中直接执行
要直接在代码中使用 agent，请实例化 RootAgent 并提供有关事件的用户查询。RootAgent 将管理向相应 sub-agent 的委托。
python
from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
# LiteLLM 会自动为 'ollama/mistral' 模型使用本地 Ollama API
SRE_MODEL = LiteLlm(model="ollama/mistral-nemo:12b", api_base="http://localhost:11434")
2. 通过 ADK Web 使用交互式 UI
为了获得企业级的体验，您可以启动 ADK Web 界面以获取可追溯性、agent 监控和人工审批界面。请确保您的 Ollama 应用程序正在后台运行。
要启动 Web 界面，请运行：
# 启动 ADK Web 服务器的命令
python -m google.adk.web --agent root_agent
3. CLI 模拟
您还可以通过 Python 在终端中运行事件的本地模拟。在您的 agent 目录之外运行以下命令。
```
python3 incident_response/agent.py
```
按照提示触发事件、运行分诊、应用修复并生成事后复盘报告。
## 生成的文件
当在本地运行 agent 时，特定的 Python 函数会将各种与事件相关的文档写入文件系统。以下函数会创建相应的文件：
* ```incident_state.json```：由 save_manual_telemetry 函数创建和更新。
* ``incident_timeline.txt```：由 update_incident_timeline 函数追加，以维护按时间顺序排列的操作日志。
* ```notification_broadcast.log```：在广播状态更新时由 send_external_notification 函数追加。
* ```{report_type}_{uuid}.md```（例如 postmortem_report_{uuid}.md）：由 archive_validated_report 函数创建，该函数使用唯一标识符保存最终的事后复盘报告。
## 开发说明
* Agent 通过 SequentialAgent 进行编排，强制执行严格的逐步执行。RootAgent 将所有技术工作委托给 sub-agent。
* 支持通过 ADK Web 进行 CLI 模拟 (incident_response/agent.py) 和交互式 workflow。
* LLM 交互通过 LiteLlm 处理，它与本地的 Ollama Mistral 模型接口对接。
* RemediationAgent 中强制执行 Human-in-the-Loop 逻辑：未经操作员明确批准，无法执行高风险操作。
* 事件数据以 JSON、文本和 Markdown 文件 (incident_state.json、incident_timeline.txt、{report_type}_{uuid}.md) 的形式持久化，以供审计。
* 建议使用虚拟环境 (venv) 来隔离依赖项。
* 日记录通过 agent 的 update 函数处理；所有操作都会追加到事件时间线中。
* RootAgent 从不直接进行技术分析；它负责编排其他 agent 以执行专门的任务。
标签：AI风险缓解, DLL 劫持, SRE, 人机协同, 偏差过滤, 大语言模型, 智能体工作流, 运维自动化, 逆向工具