melbrbry/devops-incident-swarm

# DevOps 故障响应集群 **一个分层多智能体系统，用于调查生产环境故障、在人工批准后提出缓解措施，并起草免责事后总结——具备严格的智能体 RBAC 和全面的可观测性。** 基于 **LangGraph**、**Groq** 和 **Langfuse** 构建。旨在作为一个具备作品集级别的示例，展示如何在类似生产环境的安全条件下运行 Supervisor–Worker 智能体集群。 ## 为什么开发这个项目 值班工程师不会在没有监督的情况下让 LLM 重启 pod。该系统对这一现实情况进行了建模： - **专业化智能体** 具有严格的工具边界（只读 vs 读写 vs 仅输出） - **基于代码的 Supervisor 路由** 作用于共享状态 —— 可预测、可测试、可追踪 - **人机交互 (HITL)** 在任何破坏性操作之前通过 LangGraph 的 `interrupt()` 进行 - **两阶段 Mitigator** —— 首先提出结构化 JSON，仅在批准后才执行写入工具 - **端到端可观测性** —— Supervisor 路由决策和 LLM span 均在 Langfuse 中记录 它不是一个简单的聊天机器人包装器。它是一个**以智能体为节点的状态机**，其中每一步都会修改 `IncidentState`，并由 Supervisor 决定下一步的操作。 ## 工作原理 ``` flowchart TD Alert[PagerDuty alert] --> Supervisor Supervisor -->|no root_cause| Investigator Supervisor -->|no proposed_fix| Mitigator Supervisor -->|resolved| Comms Supervisor -->|failed or done| EndNode[END] Investigator --> Supervisor Mitigator --> Supervisor Comms --> Supervisor subgraph mitigator [Mitigator subgraph] Propose[propose] --> Approval[await_approval HITL] Approval -->|Y| Execute[execute write tool] Approval -->|N| Propose Execute --> Check[check_resolution] Check -->|unresolved| Propose end ``` ### 故障处理流程 | 步骤 | 智能体 | 执行的操作 | |------|-------|----------------| | 1 | **Supervisor** | 读取 `IncidentState`，路由到下一个 Worker | | 2 | **Investigator** | 调用 `query_metrics` + `fetch_recent_logs`，输出根本原因 | | 3 | **Supervisor** | 看到 `root_cause`，路由至 Mitigator | | 4 | **Mitigator** | 提出操作 → **暂停等待人工批准** → 执行 `restart_pod` 或 `rollback_deployment` | | 5 | **Supervisor** | 看到 `status=resolved`，路由至 Comms | | 6 | **Comms** | 起草结构化的事后总结 Markdown | | 7 | **Supervisor** | 看到 `post_mortem`，结束运行 | ### 智能体 RBAC | 智能体 | 访问权限 | 工具 | |-------|--------|-------| | Investigator | 只读 | `query_metrics`, `fetch_recent_logs` | | Mitigator | 写入 (受控) | `restart_pod`, `rollback_deployment` | | Comms | 仅输出 | — | | Supervisor | 仅路由 | — (纯 Python，无 LLM) | ## 值得强调的设计决策 **拆分提议与执行 (Mitigator)。** Groq 无法在单个请求中同时进行工具调用和严格的 JSON schema。单一的 ReAct 智能体也倾向于在生成提案之前就执行写入工具。解决方案是：使用两个具有相同角色的智能体 —— 提议者（仅输出结构化内容，无工具）以及执行者（仅使用工具）。 **Supervisor 是代码，而不是 LLM。** 路由规则按优先级排序并经过单元测试（`root_cause_missing` → Investigator，`proposed_fix_missing` → Mitigator 等）。Langfuse 会记录每一个决策及其 `matched_rule` 和脱敏后的状态快照。 **通过 LangGraph interrupt 实现 HITL。** `await_approval` 会在任何写入工具运行之前调用 `interrupt()`。CLI 会提示 `[URGENT] Mitigator proposes: Rollback auth-service. Approve? (Y/N)`。如果拒绝，会将上下文反馈给提议者以生成替代方案。 **模拟基础设施，真实编排。** 故障在内存中模拟（`memory_leak`，`bad_deployment`）。智能体图、RBAC、HITL 和追踪机制均按照生产环境标准构建。 ## 技术栈 | 层级 | 选择 | |-------|--------| | 编排 | LangGraph (分层图 + checkpointer) | | LLM | 通过 `langchain-groq` 调用的 Groq (`openai/gpt-oss-120b`) | | 结构化输出 | 严格的 JSON schema (`StrictChatGroq`) | | 模拟基础设施 | FastAPI + 内存版 `Simulator` | | HITL | LangGraph `interrupt()` + `Command(resume=...)` | | 可观测性 | Langfuse (`CallbackHandler` + `@observe` span) | | 配置 | Pydantic Settings | | 测试 | pytest (包含 LLM e2e 的 78 个测试) | ## 快速开始 ### 前置条件 - Python 3.11+ - [Groq API 密钥](https://console.groq.com/) (必填) ### 安装 ``` git clone https://github.com/melbrbry/devops-incident-swarm.git cd devops-incident-swarm python -m venv .venv source .venv/bin/activate pip install -e ".[dev]" cp .env.example .env # 在 .env 中设置 GROQ_API_KEY ``` ### 运行完整的故障处理 ``` # 自动批准 write 操作（适用于演示和 CI） incident-swarm --yes --service auth-service --scenario memory_leak # 交互式 — 在 restart/rollback 前提示 incident-swarm --service auth-service --scenario bad_deployment ``` 成功运行时的预期结果： - `Status: resolved` - 打印出的根本原因和建议的修复方案 - 结尾处提供完整的免责事后总结 Markdown - 可选的 Langfuse 会话 ID，用于追踪查询 无需单独的 mock API 服务器 —— CLI 会直接针对内存模拟器触发警报。 ### 可选：Mock HTTP API ``` mock-infra # FastAPI on :8080 — /trigger_alert, /health, etc. ``` ## 配置 | 变量 | 是否必填 | 描述 | |----------|----------|-------------| | `GROQ_API_KEY` | 是 | Groq LLM API 密钥 | | `GROQ_MODEL` | 否 | 默认值: `openai/gpt-oss-120b` | | `HITL_AUTO_APPROVE` | 否 | 设置为 `true` 时跳过批准提示 | | `LANGFUSE_PUBLIC_KEY` | 否 | 启用追踪 | | `LANGFUSE_SECRET_KEY` | 否 | 启用追踪 | | `LANGFUSE_BASE_URL` | 否 | 例如 `https://cloud.langfuse.com` 或 `https://us.cloud.langfuse.com` | | `LANGFUSE_ENABLED` | 否 | 设置为 `false` 以禁用追踪 | 有关所有选项，请参见 [`.env.example`](.env.example)。 ## 可观测性 配置 Langfuse 密钥后，每次运行都会输出： - **`supervisor_route` span** — `matched_rule`、`next_agent`、脱敏后的状态 (`has_root_cause`、`has_proposed_fix` 等) - **LLM + tool span** — Investigator 指标/日志、Mitigator 提议者/执行者、Comms 事后总结 - **会话分组** — 通过标签 `incident-swarm` 或打印出的会话 ID 进行过滤 ``` incident-swarm --yes # Langfuse traces：https://cloud.langfuse.com（按 tag incident-swarm 或 session_id 筛选） # Session ID： ``` ## 测试 ``` # 快速 — 无 API 调用 pytest tests/ -m "not llm" # 完整套件 — 需要 GROQ_API_KEY pytest tests/ ``` 测试覆盖率包括 Supervisor 路由规则、HITL 批准解析、Mitigator 子图编译、Mock 基础设施模拟器以及端到端图运行。 ## 项目结构 ``` devops-incident-swarm/ ├── agents/ # Worker personas (Investigator, Mitigator, Comms) ├── graph/ # LangGraph hierarchy — state, nodes, supervisor routing ├── hitl/ # Interrupt helpers, terminal approval, resume ├── mock_infra/ # Simulated outages + FastAPI + LangChain tools ├── observability/ # Langfuse tracing bootstrap ├── scripts/ # incident-swarm, mock-infra CLIs └── tests/ ``` 更详细的构建说明：[docs/IMPLEMENTATION_PLAN.md](docs/IMPLEMENTATION_PLAN.md)

标签：LangGraph, LLM代理, PyRIT, 人机协同, 多智能体系统, 安全规则引擎, 自动化运维, 逆向工具