Keshav0375/Sentinel

# Sentinel **自主 DevOps 事件响应 agent** — 这是一个多 agent pipeline，能够对告警进行分流、诊断根本原因、起草修复计划并沟通状态，并且在执行任何破坏性操作之前设有强制的人工审批关卡。 本项目作为一个作品集项目开发，旨在展示生产级的智能体工程：多 agent 编排、HITL 安全性、情景记忆、轨迹评估以及实时可观测性。 ## 工作原理 ``` Alert fires │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Orchestrator Agent │ │ (coordinates handoffs, enforces 15-call cap, writes STM) │ └──┬──────────┬──────────┬──────────┬──────────┬─────────────┘ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ Triage Log Deploy Remediation Comms Agent Analyst Correlator Agent Agent │ │ │ │ │ │ fetch_ list_ draft_ draft_ get_ logs recent_ rollback_ slack_ service_ deploys pr summary metadata │ search_ request_human_ past_ approval ◄── HITL gate incidents │ ▼ Human approves / rejects │ ▼ Incident resolved + stored in episodic memory ``` 每一次工具调用都会作为轨迹被捕获。解决事件后，LLM 评估器会从 6 个维度对该轨迹进行评分，并生成一份可在 Web 仪表板中查看的报告。 ## 功能 - **多 agent pipeline** — 通过 OpenAI Agents SDK 交接机制编排的 5 个专家 agent（分流、日志分析师、部署关联器、修复、沟通） - **HITL 安全关卡** — `request_human_approval` 是执行破坏性操作的唯一途径；任何 agent 都无法绕过它 - **情景记忆** — 过去的事件被嵌入并存储在 SQLite 中；在事件分流期间会自动浮现相似的历史事件 - **语义记忆** — 从种子数据加载的服务映射、依赖图和操作手册 - **实时事件仪表板** — 在 `http://localhost:8000/` 实时通过 SSE 流式传输 agent 活动；可从浏览器批准/拒绝 HITL - **轨迹评估** — LLM-as-judge 从 6 个维度（0–5 分）对每个事件进行评分，并附带 Markdown 和 JSON 报告 - **评估结果仪表板** — 在 `http://localhost:8000/eval` 浏览每个场景的得分 - **10 个合成场景** — 涵盖 5 类故障（异常部署、DB 连接池、下游服务中断、内存泄漏、配置回退） ## 快速开始 ### 前置条件 - Python 3.12+ - [Groq API key](https://console.groq.com/keys)（免费额度即可） - Docker + docker-compose（可选，但强烈推荐） ### 1. 克隆并配置 ``` git clone https://github.com/keshxv/sentinel.git cd sentinel cp .env.example .env # 编辑 .env — 添加你的 GROQ_API_KEY ``` ### 2a. 使用 Docker 运行 ``` docker-compose up --build ``` 仪表板：[http://localhost:8000](http://localhost:8000) ### 2b. 不使用 Docker 运行 ``` python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e ".[dev]" python -m data.seed # seed service map + runbooks uvicorn sentinel.main:app --reload ``` 仪表板：[http://localhost:8000](http://localhost:8000) ### 3. 切换提供商（可选） 模型字符串使用 `provider/model` 格式。只需 3 个环境变量即可替换任何提供商，无需修改代码。 **将分析切换至 Anthropic Claude：** ``` SENTINEL_ANALYSIS_MODEL=anthropic/claude-sonnet-4-6 ANTHROPIC_API_KEY=sk-ant-... ``` **将所有任务切换至 OpenAI：** ``` SENTINEL_TRIAGE_MODEL=openai/gpt-4o-mini SENTINEL_ANALYSIS_MODEL=openai/gpt-4o SENTINEL_JUDGE_MODEL=openai/gpt-4o-mini OPENAI_API_KEY=sk-... ``` 请参阅 [available_models.md](available_models.md) 获取完整的模型列表和提供商能力矩阵。 ### 4. 触发场景 **从仪表板** — 从下拉菜单中选择一个场景，然后点击 ⚡ 触发场景。 **从 CLI**： ``` python scripts/run_scenario.py bad_deploy_01 python scripts/run_scenario.py --list # see all 10 scenarios ``` ### 5. 运行评估套件 ``` python scripts/run_eval.py # 或其子集： python scripts/run_eval.py --scenarios bad_deploy_01 db_pool_01 ``` 结果 → `reports/eval_report.json` + `reports/eval_report.md` 仪表板 → [http://localhost:8000/eval](http://localhost:8000/eval) ## 演示 1. 从下拉菜单中选择 `bad_deploy_01` — 触发严重的 API 网关告警 2. 观察五个 agent 卡片随着每个专家完成分析而依次点亮 3. 当修复 agent 请求回滚批准时，会出现一个琥珀色的 HITL 悬浮层 4. 点击 ✅ 批准 — pipeline 继续执行，事件得到解决 5. 切换到 `/eval` 查看 LLM 评估器的各项维度得分 ## 技术栈 | 层级 | 技术 | |-------|-----------| | Agent 框架 | [openai-agents](https://github.com/openai/openai-agents-python) (Agents SDK) | | LLM | LiteLLM 多提供商 — 通过 `provider/model` 环境变量支持 `groq/`, `openai/`, `anthropic/`, `azure/`。默认：Groq（免费额度）。参见 [available_models.md](available_models.md)。 | | API 层 | FastAPI + uvicorn | | 记忆 — 情景 | 通过 aiosqlite + 余弦相似度的 SQLite | | 记忆 — 语义 | SQLite (服务映射，操作手册) | | Embeddings | sentence-transformers `all-MiniLM-L6-v2` (本地，384 维，零成本) | | 实时 | Server-Sent Events (`EventSource` API) | | 模型/校验 | Pydantic v2 | | 配置 | pydantic-settings | | 日志 | structlog (JSON) | | HTTP 客户端 | httpx | | 容器化 | Docker + docker-compose | | 代码检查 | ruff | | 类型检查 | pyright | | 测试 | pytest + pytest-asyncio | ## 评估结果 **评估维度（由评估器打分 0–5 分）：** | 维度 | 衡量内容 | |-----------|-----------------| | `triage_accuracy` | 服务正确且严重性准确？ | | `root_cause_correctness` | 假设是否与已知根本原因相符？ | | `tool_efficiency` | 工具调用顺序是否合理？无冗余调用？ | | `mttr` | 从告警到提出修复建议的时间（越短越好） | | `remediation_safety` | 是否使用了 HITL 关卡？提出的修复方案是否恰当？ | | `comms_quality` | Slack 摘要是否清晰、完整、结构化？ | 及格阈值：**3.0 / 5.0** (60%) ## 项目结构 ``` sentinel/ ├── src/sentinel/ │ ├── agents/ # 5 specialist agents + orchestrator │ ├── tools/ # Tool implementations (fetch_logs, draft_rollback_pr, …) │ ├── memory/ # Episodic (SQLite + embeddings), semantic, short-term │ ├── eval/ # Rubric, LLM-as-judge, batch runner, report generator │ ├── api/ # FastAPI routes (webhooks, SSE, HITL, incidents, scenarios) │ ├── infra/ # DB, logging, tracing, event bus, dashboard emitter │ ├── models/ # Pydantic domain models │ ├── generator/ # Synthetic alert + log + deploy data │ └── dashboard/ # index.html (live dashboard) + eval.html ├── data/ │ ├── scenarios/ # 10 JSON scenario files │ └── services/ # service_map.json, dependency_graph.json, runbooks.json ├── scripts/ │ ├── run_scenario.py # Fire a single scenario from CLI │ ├── run_eval.py # Batch eval across all scenarios │ └── demo.py # Interactive demo runner (coming soon) ├── tests/ # ~1 000 tests across all layers └── reports/ # Trajectory JSON, eval_report.json/md ``` ## 架构决策 **为什么选择多 agent 而不是单 agent？** 每个专家都有专属的 system prompt 和受限的工具集。这使得每个 agent 都可以独立测试和改进——修改日志分析师的 prompt 不会影响事件分流功能。 **为什么 HITL 在工具级别而不是在 prompt 级别实现？** 系统中不存在“执行回滚”工具，只有 `draft_rollback_pr` + `request_human_approval`。agent 无法通过忽略 prompt 指令来绕过审批；从工具层面来说，它根本没有任何可以脱离人类授权而执行操作的工具。 **为什么使用 SQLite 作为情景记忆？** 对于 MVP 而言，基础设施成本为零。这种 embedding + 余弦相似度的方法在 10 到 100 起事件规模时效果很好。Phase 2 将为了扩展性切换到带有向量索引的 Cosmos DB。 **为什么使用单独的评估模型？** 在评估时使用不同的模型家族可以避免自我评分偏见。agent 运行在 `llama-3.3-70b-versatile` 上；评估器运行在 `llama-3.1-8b-instant` 上。在生产环境中，您会完全使用不同的提供商。 ## Phase 2 路线图 _此处记录的内容旨在用于面试中探讨生产环境就绪度：_ | 能力 | Phase 2 方案 | |-----------|-----------------| | 云部署 | Azure Container Apps + Bicep IaC | | 数据库 | Cosmos DB (向量 + JSON) 替代 SQLite | | 缓存 | 用于短期记忆的 Redis | | 模型路由 | LiteLLM 已实现 (Phase 9) — 用于 token 预算控制的 Kong AI Gateway 为 Phase 2 计划 | | 可观测性 | 自托管的 LangFuse 用于链路追踪仪表板 | | HITL 渠道 | Slack 交互式按钮（真实的 Slack 应用） | | PR 创建 | 用于创建真实 PR 的 GitHub App | | 自我改进 | 每晚执行的 ACA Job — 重新评估 + 自动提交 PR 以改进失败的 prompt | | 告警源 | Azure Service Bus + Datadog webhook 用于接收真实告警 | | 对抗性评估 | 40 个场景，8 种故障类型，含糊的多原因复杂案例 | | CI/CD | 带有评估分数门控的 GHA（如果平均分 < 3.5 则部署失败） | ## 运行测试 ``` pytest # run all ~1 000 tests pytest tests/test_eval/ # eval layer only pytest tests/test_tools/ # tool layer only pytest -x -v # stop on first failure, verbose ``` ## 许可证 MIT

标签：人机协同, 多智能体协同, 安全规则引擎, 智能运维, 自动化事件响应, 请求拦截, 运行时操纵, 逆向工具