alparn/sre-agent
GitHub: alparn/sre-agent
这是一个自托管的 AI SRE 代理，用于自动化生产事件响应，并通过 Markdown 记忆系统积累运维知识。
Stars: 0 | Forks: 0
# SRE 代理
[](https://github.com/alparn/sre-agent/actions/workflows/ci.yml)
[](https://github.com/alparn/sre-agent/actions/workflows/security.yml)
[](LICENSE)
[](pyproject.toml)
[](Dockerfile)
```
flowchart LR
A[Alertmanager / Webhook] --> B[OBSERVE]
B --> C[REASON]
C --> D{Approval Gate}
D -->|read-only| E[ACT]
D -->|risky action| F[Human Approval]
F --> E
E --> G[LEARN]
G --> H[Markdown Vault]
H --> C
B --> I[Prometheus]
B --> J[Loki]
B --> K[Tempo]
E --> L[Kubernetes / Runbooks]
E --> M[Slack / PagerDuty / GitHub]
```
## 为什么选择 SRE Agent？
生产事件往往嘈杂、分散且重复。SRE Agent 为团队提供了一个透明的 AI 事件调查员，它在本地运行，将记忆存储在纯文本 Markdown 中，并在触及生产环境前使用审批门。
| 问题 | SRE Agent 的方法 |
|------|------------------|
| 告警缺乏上下文 | 将日志、指标、追踪、拓扑和部署信息整合到一个循环中 |
| AI 工具感觉像黑盒 | 明确的 `OBSERVE -> REASON -> ACT -> LEARN` 状态机 |
| 厂商锁定 | 自托管、基于适配器、与 LiteLLM 兼容的模型路由 |
| 事件知识丢失 | 将可复用的运行手册、服务说明和模式写入知识库 |
| 补救风险高 | 对破坏性或更改生产环境的操作设置人工审批门 |
### 比较
| 功能 | SRE Agent | HolmesGPT | Microsoft SRE Agent | Lucas |
|------|-----------|-----------|---------------------|-------|
| 自托管 | 是 | 是 | 部分 | 是 |
| Markdown/Obsidian 记忆 | 是 | 否 | 否 | 否 |
| 审批门 | 是 | 部分 | 是 | 部分 |
| LiteLLM 模型路由 | 是 | 否 | 否 | 否 |
| Grafana 技术栈演示 | 是 | 是 | 否 | 部分 |
| 可扩展适配器模式 | 是 | 是 | 部分 | 部分 |
## 功能
### 核心事件响应
- Alertmanager 和通用 webhook 触发器
- 确定性的 `OBSERVE -> REASON -> ACT -> LEARN` 调查循环
- 具有令牌预算管理和压缩的上下文感知推理
- 针对高风险补救操作的人工审批门
### 可观测性集成
- Prometheus 指标查询
- Loki 日志搜索
- Tempo 追踪查询
- Grafana 技术栈适配器接口
- 部署和拓扑发现
### 操作与自动化
- Kubernetes Pod 重启、扩缩容和回滚工具
- 数据库锁检查和查询终止工具
- 具有审批控制的运行手册执行
- 用于安全诊断脚本的代码沙箱
### 记忆与学习
- 兼容 Obsidian 的 Markdown 知识库
- 事件、服务、模式和运行手册模板
- 知识库搜索与召回工具
- 基线与拓扑历史跟踪
### 通知与协作
- 由 Composio 驱动的 Slack、PagerDuty、GitHub 和 Linear 集成
- 结构化的事件摘要
- 用于事后复盘的工具调用审计追踪
## 快速开始
### 前置条件
| 工具 | 版本 |
|------|------|
| Python | 3.12+ |
| uv | 最新 |
| Docker | 24.0+ |
| Docker Compose | v2+ |
你还需要：
- 一个用于 LiteLLM 的 Anthropic 或 OpenAI API 密钥
- 一个用于外部通知和工单系统集成的 Composio API 密钥
### 方案一：Docker Compose（推荐）
```
git clone https://github.com/alparn/sre-agent.git
cd sre-agent
cp .env.example .env
docker compose -f docker-compose.yaml -f demo/docker-compose.demo.yaml up --build
```
打开本地服务：
| 服务 | URL |
|------|-----|
| SRE Agent API | http://localhost:8000 |
| Grafana | http://localhost:3001 |
| Prometheus | http://localhost:9090 |
| Alertmanager | http://localhost:9093 |
| LiteLLM | http://localhost:4000 |
### 方案二：从源代码
```
git clone https://github.com/alparn/sre-agent.git
cd sre-agent
uv sync --group dev
cp .env.example .env
uv run uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
```
### 方案三：Kubernetes / Helm
Kubernetes 部署清单和 Helm chart 正在规划中。在此之前，请使用 Docker 镜像并按照下文记录的相同环境变量进行配置。
## 2 分钟处理第一个事件
启动演示技术栈：
```
docker compose -f docker-compose.yaml -f demo/docker-compose.demo.yaml up --build
```
触发一个合成事件：
```
uv run python scripts/run_demo_incident.py
```
预期结果：
```
Investigation started
Alert: HighErrorRate
Service: demo-service
Agent loop: OBSERVE -> REASON -> ACT -> LEARN
Vault entry written under vault/incidents/
```
你也可以直接触发 webhook：
```
curl -X POST http://localhost:8000/webhook \
-H "Content-Type: application/json" \
-d '{
"title": "High API error rate",
"service": "demo-service",
"severity": "critical",
"description": "5xx error rate exceeded threshold"
}'
```
## 架构
SRE Agent 的设计有意避免使用重量级的 Agent 框架。其运行时是一个小型、可检查的循环，包含类型化工具、模型路由和审批门。
| 组件 | 职责 |
|------|------|
| `src/main.py` | FastAPI webhook、健康检查、依赖连接 |
| `src/agent/` | Agent 循环、上下文、状态转换、审批门 |
| `src/tools/observe/` | 日志、指标、追踪、告警、拓扑、部署 |
| `src/tools/diagnose/` | 关联、异常检测、指标差异 |
| `src/tools/act/` | Kubernetes、数据库、运行手册和沙箱操作 |
| `src/tools/memory/` | 知识库读取/写入/搜索/召回工具 |
| `src/adapters/` | 可观测性后端抽象 |
| `src/vault/` | Markdown 知识库写入器、读取器、搜索器和索引器 |
| `src/compression/` | 令牌预算、规则摘要、LLM 压缩 |
| `src/integrations/` | 由 Composio 支持的外部集成 |
## 配置
```
cp .env.example .env
```
### 环境变量
| 变量 | 必需 | 描述 |
|------|------|------|
| `ANTHROPIC_API_KEY` | 需要一个 LLM 密钥 | LiteLLM 使用的 Anthropic 密钥 |
| `OPENAI_API_KEY` | 需要一个 LLM 密钥 | LiteLLM 使用的 OpenAI 密钥 |
| `COMPOSIO_API_KEY` | 是 | 启用 Slack、PagerDuty、GitHub、Linear 工具 |
| `GRAFANA_ADMIN_USER` | 否 | 本地 Grafana 用户，默认为 `admin` |
| `GRAFANA_ADMIN_PASSWORD` | 否 | 本地 Grafana 密码，默认为 `admin` |
| `GRAFANA_PORT` | 否 | 本地 Grafana 端口，默认为 `3001` |
| `SRE_AGENT_CONFIG_PATH` | 否 | 覆盖运行时配置路径 |
### 最小配置
```
agent:
max_iterations: 8
default_severity: warning
observability:
provider: grafana
grafana:
prometheus_url: http://prometheus:9090
loki_url: http://loki:3100
tempo_url: http://tempo:3200
vault:
path: /app/vault
index_path: /app/vault/.index.sqlite
approval:
require_human_for:
- restart_pod
- scale_deployment
- rollback_deployment
- db_kill_query
```
## 集成
| 类别 | 支持 | 规划中 |
|------|------|--------|
| 指标 | Prometheus | Datadog, CloudWatch |
| 日志 | Loki | Elastic, Splunk |
| 追踪 | Tempo | Jaeger |
| 告警 | Alertmanager, webhook | PagerDuty, Opsgenie |
| LLM | Anthropic, OpenAI, 通过 LiteLLM 支持 Ollama | Gemini |
| 聊天和工单 | 通过 Composio 支持 Slack, GitHub, Linear | Teams, Discord |
| 运行时 | Docker Compose | Helm, Kubernetes 清单 |
## 工作原理
1. **触发**：Alertmanager 或 webhook 发送事件负载。
2. **观察**：Agent 收集受影响服务的指标、日志、追踪、部署历史和拓扑信息。
3. **推理**：模型路由器询问配置的 LLM 接下来应收集哪些证据或提出哪些安全操作。
4. **执行**：只读工具自动运行。高风险工具需通过审批门。
5. **学习**：最终摘要、证据和可复用模式被写入本地 Markdown 知识库。
## 开发
```
uv sync --group dev
uv run ruff check .
uv run ruff format .
uv run pytest
```
## 安全
- 不要提交 `.env`、API 密钥、知识库数据、日志或数据库文件。
- 所有密钥必须来自环境变量或密钥管理器。
- 破坏性操作需要明确批准。
- 参见 [SECURITY.md](SECURITY.md) 了解负责任的披露。
## 路线图
- Datadog 和 CloudWatch 适配器
- Helm chart 和生产环境 Kubernetes 清单
- GitHub Codespaces 演示环境
- 事后复盘生成
- 额外的记忆后端
- 多租户审批策略
## 许可证
SRE Agent 使用 [Apache License 2.0](LICENSE) 许可证。
示例调查输出
``` Incident: High API error rate Evidence: - Prometheus: 5xx rate increased from 0.2% to 8.7% - Loki: token validation failures started after deployment api-7f9d4 - Tempo: p95 latency increased on /auth/validate Likely cause: Recent auth middleware deployment rejects valid tokens for one tenant. Recommended action: Rollback deployment api-7f9d4 after human approval. Vault updates: - incidents/2026-05-19-high-api-error-rate.md - patterns/token-validation-failures.md ```标签：AIOps, AI代理, AI助手, AI运维, Docker, Loki, Markdown记忆, Python, runbook生成, SRE, SRE工具, Tempo, 事件管理, 事件调查, 事故自动化, 偏差过滤, 可观察性, 基础设施监控, 子域名突变, 安全防御评估, 应用性能管理, 批准门, 技术教程, 指标监控, 无后门, 服务笔记, 本地部署, 模式识别, 状态机, 监控, 知识管理, 站点可靠性工程, 网络调试, 自动化, 自定义请求头, 自托管, 请求拦截, 运维工具, 运维自动化, 追踪, 适配器, 逆向工具