suryaanandan1995-dotcom/agentic-sre-platform

# Agentic SRE Platform [](https://www.python.org/) [](https://github.com/langchain-ai/langgraph) [](https://github.com/langchain-ai/langchain) [](https://www.anthropic.com/) [](https://github.com/kubernetes-client/python) [](https://github.com/suryaanandan1995-dotcom/agentic-sre-platform/actions/workflows/ci.yml) [](LICENSE) ## 概述 Agentic SRE Platform 可自动执行 Kubernetes 事件的第一响应循环。 它没有使用单一的庞大 prompt，而是将**四个专用 agent** 组合成一个 LangGraph 状态机。 每个 agent 负责一项职责，并将一个类型化的 state 对象传递给下一个： - **Detector** 扫描集群并引发最严重的候选事件。 - **Diagnostician** (Claude) 对事件、日志和 Prometheus 指标进行推理，以得出带有校准置信度分数的根本原因。 - **Remediator** 将诊断结果映射为保守、可逆的操作，并且仅在获得允许时执行它们。写入操作**默认处于 dry-run 模式**。 - **Reporter** (Claude) 编写一份无指责的 Markdown 复盘报告。 agent 之间的条件边决定是自动修复、暂停等待人工审批，还是升级。 整个 pipeline 可以通过 CLI 运行，也可以作为集群内的 CronJob 运行。 ## 它解决的问题 待命工程师在每次事件发生的前几分钟都在做相同的机械性工作：注意到工作负载处于不健康状态、拉取其事件和日志、与指标进行关联、形成假设、应用安全修复，并在事后将其编写成文。 这项工作重复性高，在凌晨 3 点容易出错，而且很少能保持一致的文档记录。 该平台将这一循环编码为协作的 agent，从而实现： - **检测是即时且确定性的** —— 无需 LLM 成本或延迟即可注意到 CrashLoopBackOff。 - **诊断是有根据的** —— Claude 基于从集群和 Prometheus 获取的*真实*证据进行推理，而非猜测，并报告其置信度。 - **操作在构建上是安全的** —— 每次写入都受到 `dry_run`（默认开启）和可选的人工审批边的限制，并由最小权限 RBAC 提供支持。 - **每次事件都有记录** —— 每次运行都会生成一份复盘报告，即使未采取任何行动。 ## 架构  该 pipeline 是一个基于类型化 `SREState`（一个携带事件、发现、建议操作和报告的 `TypedDict`）的 `langgraph.StateGraph`： ``` Detector ──▶ Diagnostician ──▶ ⟨route⟩ ──▶ Remediator ──▶ Reporter ──▶ END │ └─(escalate / no incident)─▶ Reporter ``` 诊断之后的条件边会选择一个**处理方式**： | 处理方式 | 条件 | 效果 | | ----------------- | ----------------------------------------------------------------- | --------------------------------------------- | | `auto_remediate` | 置信度 ≥ 0.4 且（无需审批 *或* 已获批） | Remediator 执行（受限于 `dry_run`） | | `human_approval` | 置信度 ≥ 0.4 但需要审批且未获批 | Remediator 仅提出建议；等待人工处理 | | `escalate` | 置信度 < 0.4，或无事件 | 跳过修复；直接进入报告阶段 | ## Agent 角色 | Agent | 职责 | 工具 | | ----------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------- | | **Detector** | 扫描命名空间，引发最严重的候选事件 | `list_unhealthy_pods` (k8s) | | **Diagnostician** | 从证据中找出事件的根本原因；输出置信度 + 操作 | `get_pod_events`, `get_pod_logs` (k8s)；CPU/内存/错误率 (Prom)；通过 `ChatAnthropic.bind_tools` 调用 Claude | | **Remediator** | 提出并选择性执行修复；强制执行 dry-run 和审批门控 | `restart_deployment`, `scale_deployment`, `delete_pod` (k8s，受控) | | **Reporter** | 编写无指责的 Markdown 复盘报告 | 通过 `ChatAnthropic` 调用 Claude | ## 仓库结构 ``` agentic-sre-platform/ ├── agents/ │ ├── __init__.py │ ├── state.py # TypedDict graph state (Incident, Finding, ...) │ ├── llm.py # ChatAnthropic factory (claude-opus-4-8) │ ├── detector.py # scans cluster, emits candidate incident │ ├── diagnostician.py # LLM root-cause over logs/events/metrics │ ├── remediator.py # proposes + executes fix (dry-run gated) │ ├── reporter.py # writes Markdown postmortem │ └── graph.py # LangGraph StateGraph + run() entrypoint ├── tools/ │ ├── __init__.py │ ├── k8s_tools.py # Kubernetes read/write tools (write = dry-run gated) │ └── metrics_tools.py # Prometheus query tools ├── prompts/ │ ├── detector.md │ ├── diagnostician.md │ ├── remediator.md │ └── reporter.md ├── tests/ │ ├── __init__.py │ ├── conftest.py # fake ChatModel + mocked k8s/metrics │ ├── test_graph.py # graph transitions & dispositions │ └── test_tools.py # dry-run safety + metrics parsing ├── k8s/ │ ├── cronjob.yaml # in-cluster scheduled run │ ├── rbac.yaml # least-privilege ServiceAccount + ClusterRole │ └── secret.example.yaml ├── docs/ │ └── architecture.drawio # editable architecture diagram ├── main.py # CLI (--dry-run/--no-dry-run, --namespace, --once/--watch) ├── Dockerfile ├── requirements.txt ├── pyproject.toml ├── .github/workflows/ci.yml ├── .env.example ├── .gitignore └── LICENSE ``` ## 前置条件 - **Python 3.11+** - 一个有效的 **kubeconfig**（或集群内的 ServiceAccount），具有对 pods/events/logs 的读取权限；若需进行实际修复，还需具备 [`k8s/rbac.yaml`](k8s/rbac.yaml) 中定义的 patch/delete 权限。 - 一个用于 Claude 的 **`ANTHROPIC_API_KEY`**（由 `langchain-anthropic` 从环境中读取）。 - 可选：一个可访问的 **Prometheus** endpoint (`PROMETHEUS_URL`)，用于指标关联。 ## 快速开始 ``` # 1. 创建并激活 virtual environment python -m venv .venv source .venv/bin/activate # 2. 安装依赖 pip install -r requirements.txt # 3. 配置环境 cp .env.example .env export ANTHROPIC_API_KEY="sk-ant-..." # or set it in .env # 4. 对默认 namespace 运行单次安全（dry-run）检查 python main.py --dry-run --namespace default ``` 其他模式： ``` # 每 60 秒持续监控一个 namespace（仍为 dry-run） python main.py --dry-run --namespace payments --watch --interval 60 # 允许真实修复，但需要先经过人工审批 python main.py --no-dry-run --require-approval --namespace payments # 运行离线 test suite（无需 API key，无需 cluster） pytest -q ``` ## 安全性 修复功能在设计上默认是安全的： - **默认开启 dry-run。** 每个写入工具（`restart_deployment`、`scale_deployment`、`delete_pod`）都带有一个默认为 `True` 的 `dry_run` 标志。在 dry-run 模式下，工具仅描述它们*将要*做什么，而绝不调用 Kubernetes 的写入 API。你必须显式传递 `--no-dry-run` 才能更改集群。 - **人工审批边。** 使用 `--require-approval` 时，条件图边会将置信度高但敏感的事件路由到 `human_approval`：Remediator 仅提出操作建议，除非设置 `approved=True` 并重新运行图，否则不会执行。 - **不确定时升级。** 低于置信度阈值的诊断将升级给人工处理，而不是自动执行。 - **保守的操作集。** Remediator 仅提出可逆操作（rollout 重启、重建 pod、扩缩容）。镜像/凭证失败会被标记为 `manual`，而不是盲目重启工作负载。 - **最小权限 RBAC。** [`k8s/rbac.yaml`](k8s/rbac.yaml) 仅授予 pod/event/log 读取权限以及 Remediator 所需的特定 patch/delete 权限 —— 没有访问 secrets 的权限，没有节点访问权限，也没有 cluster-admin 权限。容器以非 root 用户身份运行，具有只读根文件系统，并且删除了所有 capabilities。 ## CI/CD GitHub Actions ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) 在每次推送到 `main` 和 pull request 时运行： 1. Checkout (`actions/checkout@v4`) 2. 设置 Python 3.11 (`actions/setup-python@v5`) 3. `pip install -r requirements.txt` 4. `ruff check .` — lint 5. `pytest -q` — 完整的测试套件，**完全离线**运行（伪造 Claude 模型并 mock Kubernetes/Prometheus 客户端），因此 CI 不需要 API 密钥和集群。 该 workflow 声明了 `permissions: contents: read`。[`Dockerfile`](Dockerfile) 构建了一个适合集群内 [`k8s/cronjob.yaml`](k8s/cronjob.yaml) 使用的最小化非 root 镜像。 ## 许可证 基于 [MIT License](LICENSE) 发布。 ## 作者 **Surya A** — DevSecOps + AI Infrastructure 工程师 - Email: suryaanandan1995@gmail.com - LinkedIn: https://www.linkedin.com/in/surya-devsecops/

标签：LangGraph, SRE, 事故响应, 偏差过滤, 子域名突变, 故障诊断, 自动化运维, 自定义请求头, 请求拦截, 逆向工具