prishitapatel09/SREagent

# SREagent — 自主 AI 事件响应器 一个在**告警触发的瞬间**响应生产环境故障的 AI 系统： 它能识别可能导致错误的 commit，找到合适的 runbook，评估用户 影响，发布 Slack 简报 —— 并在问题解决后 自动生成复盘报告。 **它的功能** 1. 即时响应 Alertmanager webhooks（包括 firing *和* resolved 状态） 2. 从服务的真实 git 历史记录中识别可能导致错误的 commit 3. 找到合适的 runbook（可解释的 BM25 匹配，而非黑盒） 4. 通过 Prometheus 确定性地评估用户影响（LLM 绝不执行数学计算） 5. 发布结构化的 Slack 事件简报（在没有 Slack 的情况下回退到控制台） 6. 自动生成复盘报告 —— 时间线与记录的事件 1:1 映射 整个系统自带了一个可破坏的“生产环境”：一个演示商店 API， 实时流量，Prometheus 告警，以及一个预先植入 bad commits 的 seeded git 历史记录 —— 这样你就可以**故意破坏生产环境，并观看 AI 的实时响应**。 ## 架构 ``` loadgen ──traffic──▶ shopapi (demo store API, feature-flag failure injection) │ /metrics │ JSON logs → shared volume ▼ ▼ Prometheus ──alert rules──▶ Alertmanager │ webhook (firing/resolved) ▼ agent (FastAPI: webhook + LLM loop + SSE + dashboard) │ tools: PromQL · logs · git log -S · runbooks · impact ▼ Qwen (Ollama, or any OpenAI-compatible endpoint) │ Slack brief ◀────┴────▶ SQLite (incidents + events) ──▶ live dashboard └──▶ postmortems/*.md ``` **让演示真实可靠的技巧：** 每次故障注入都会启用一个 feature flag， 其存在 bug 的代码路径是由 *真实 seeded git 历史记录中的特定 commit* 引入的。 运行时堆栈跟踪中的错误字符串会原封不动地出现在该 commit 的 diff 中 —— 因此 agent 能够通过真正的工具 (`git log -S`) 找到罪魁祸首，而不是通过预设的查询。 ## 快速开始 前置条件：Docker Desktop，Python 3.11+，以及（对于 live 模式）[Ollama](https://ollama.com) 运行 `ollama pull qwen3:8b` —— 或者任何兼容 OpenAI 的 endpoint。 （Linux：运行 Ollama 时加上 `OLLAMA_HOST=0.0.0.0`，以便 agent 容器能够访问它。） ``` cp .env.example .env make up # seeds the git history + starts 5 containers make demo-break # break prod (payment gateway outage) ``` 打开 http://localhost:8080 并观察事件流汇入。然后： ``` make demo-fix # heal prod -> alert resolves -> postmortem publishes ``` 没有 GPU / Ollama？`make demo-stub` 使用确定性的脚本化调查器运行 完全相同的 pipeline。 ## 10 分钟演示脚本 | 时间 | 操作 | 观众看到的内容 | |---|---|---| | 0:00 | (预置：`make up`，`make demo-check` 状态为绿色) | 健康的商店，空白的仪表盘 | | 1:00 | `git -C demo-repo/shopapi log --oneline -8` | 一个团队的 commit 历史记录；bad commit 被隐藏起来了，而不是 HEAD | | 2:00 | `make demo-break` | Checkout 开始返回 500 错误；在 Prometheus 注意到时进行讲解（约 60–90 秒） | | 3:00 | — | 事件滑入仪表盘，状态脉冲变红 | | 3:30 | — | 时间线实时流式传输：metrics → logs → `git log -S` → diff → runbook → 影响 | | 5:30 | 指向诊断卡片 | 精确植入的 commit sha 及作者，匹配的 runbook，计算出影响，Slack 简报 | | 6:30 | `make demo-fix` | 告警解除；状态翻转为绿色 | | 7:30 | — | 渲染复盘报告：元数据、影响、1:1 事件时间线、行动项 | | 8:30 | 打开 `agent/app/investigation/loop.py` | 60 秒代码概览：防护栏、强制结构化诊断、回退 | 返场演示：`make demo-break FAILURE=slow_products` 展示了延迟告警路径 （N+1 bug），这是一种完全不同的故障类别。 ## 配置 | 环境变量 | 默认值 | 用途 | |---|---|---| | `LLM_BASE_URL` | `http://host.docker.internal:11434/v1` | 任何兼容 OpenAI 的 endpoint | | `LLM_API_KEY` | `ollama` | API key（对于 Ollama 可以是任何非空字符串） | | `LLM_MODEL` | `qwen3:8b` | 模型名称（8GB 内存机器使用 `qwen3:4b`） | | `AGENT_MODE` | `live` | `live` 或 `stub`（确定性，无需 LLM） | | `SLACK_WEBHOOK_URL` | *(空)* | Slack 传入 webhook；留空 = 控制台/仪表盘卡片 | | `MAX_TOOL_CALLS` | `10` | 调查工具预算 | | `RPS` | `10` | 负载生成器流量速率 | 使用托管的 Qwen 替代本地 Ollama：设置 `LLM_BASE_URL=https://openrouter.ai/api/v1`， `LLM_API_KEY=sk-or-...`，`LLM_MODEL=qwen/qwen3-32b`（可实现最快的演示轮次）。 ## 工作原理 - **调查循环** ([loop.py](agent/app/investigation/loop.py)) — 一个针对小型开源模型强化过的 OpenAI tool-calling 循环：扁平化的工具 schema，每轮调用一个工具，结果截断，强制的终端 `submit_diagnosis` 工具（在每个兼容 OpenAI 的后端上都能工作，不像 `response_format`）， 带有一轮修复的验证，以及确定性的回退机制，从而确保 pipeline 永不陷入死胡同。 - **工具** ([tools.py](agent/app/investigation/tools.py)) — PromQL 查询，日志 追踪，`git log`/`git show`/`git log -S`，runbook 搜索，影响计算。 - **事件协议** ([events.py](agent/app/events.py), [store.py](agent/app/store.py)) — 每个调查步骤都会持久化到 SQLite 中，*然后* 通过 SSE 扇出； rowid 兼作 SSE id，因此即使跨 agent 重启，重连也可以通过 `Last-Event-ID` 进行无损重放。 - **Stub 模式** ([stub.py](agent/app/investigation/stub.py)) — 一个脚本化的 调查器，具有与 OpenAI SDK 相同的客户端接口。它驱动 真实的工具并提取真实的 commit sha，且具有确定性。它为 测试套件提供支持，并兼任演示的回退机制。 ## 测试 ``` pip install -e "./agent[test]" make test # unit + integration (stub LLM, no docker, no network) make smoke # fast CI gate: webhook fixture in -> postmortem out ``` CI 会在每次推送时运行相同的目标 (`.github/workflows/ci.yml`)。 ## 项目布局 ``` agent/ the AI agent + dashboard (FastAPI, one container) services/ shopapi (breakable demo store) + loadgen ops/ Prometheus alert rules + Alertmanager routing runbooks/ team runbooks the agent searches (3 real + 2 decoys) scripts/ seed_history.py (planted git history) + inject/resolve demo-repo/ generated: the seeded repo, also the shopapi build context postmortems/ generated postmortem markdown files ``` ## 限制与后续步骤 - 单服务演示范围；多服务关联（traces）是显而易见的扩展方向。 - Runbook 匹配是词法的 (BM25) — 在这种规模的语料库中特意这样做以保证可解释性；当 runbook 数量达到 100+ 时，使用 embeddings 会更有价值。 - Agent 负责诊断和建议，但不会自动修复；一个需要审批的“帮我禁用该 flag”操作是自然的下一个功能。 - 每个告警指纹对应一个事件；未对告警风暴关联进行建模。

标签：AIOps, AI风险缓解, LLM代理, Petitpotam, SRE, 偏差过滤, 智能应急响应, 自动化运维, 自定义请求头, 请求拦截, 逆向工具