MaazAli8460/DevOps-Guardian
GitHub: MaazAli8460/DevOps-Guardian
一个基于多智能体架构的 DevOps 事件自动检测、诊断与安全修复助手，帮助工程团队减少告警疲劳并加速事件响应。
Stars: 0 | Forks: 0
# DevOps Guardian: Multi-Agent 部署与事件响应智能助手
**DevOps Guardian** 是一个多智能体（Multi-Agent）事件检测、诊断和修复智能助手，旨在帮助软件工程团队安全地管理部署故障和服务降级。
本项目是为 **Kaggle 5-Day AI Agents: Intensive Vibe Coding Course with Google** （赛道：*Agents for Business*）开发的 Capstone 项目。
## 1. 项目概述与问题陈述
### 问题所在
现代服务部署和基础设施管理极易发生错误（例如数据库连接超时、内存耗尽、资源达到限制）。当这些故障发生时，工程团队面临两个主要挑战：
1. **告警疲劳：** 仪表盘产生大量噪音告警，导致团队最终忽视它们。
2. **事件响应缓慢：** 人类工程师必须手动登录、检查日志、进行诊断并找出修复方法（例如回滚或重启服务）——这可能需要数小时，并给公司带来收入损失。
### 解决方案：DevOps Guardian
DevOps Guardian 充当了一名自动化的 on-call 工程师：
- **轮询指标与检测异常：** 监控错误率和响应延迟。
- **通过日志分析定位根因：** 通过标准协议连接到服务器以检查日志追踪（log traces）。
- **提出安全的修复方案：** 推荐针对性的修复措施（例如回滚、重启、扩容）。
- **Human-in-the-Loop 安全门：** 严格拦截任何变更性命令，并在执行前等待管理员的明确授权。
## 2. Multi-Agent 系统架构
本项目使用 **Google's Agent Development Kit (ADK)** 设计。它将事件响应构建为一个协作智能体 pipeline，强制执行清晰的关注点分离和安全边界。
```
[Start]
│
▼
┌──────────────┐
│ MonitorAgent │ ──► Polls metrics, flags anomalies (e.g. error rate >5%)
└──────┬───────┘
│ (anomaly detected)
▼
┌──────────────┐
│DiagnosisAgent│ ──► Reads server logs via MCP tool, identifies DB Timeout
└──────┬───────┘
│ (root cause)
▼
┌──────────────┐
│ ActionAgent │ ──► Selects best remediation (e.g. rollback_deployment)
└──────┬───────┘
│ (proposal + risk tier)
▼
┌──────────────┐
│SecurityAgent │ ──► Intercepts Medium/High Risk proposals
└──────┬───────┘ Creates approval gate blocking execution
│
▼
┌──────────────┐
│ Human Gate │ ──► Admin reviews & approves via CLI command
└──────┬───────┘
│ (authorized)
▼
[MCP Execution] ──► Rollback/Restart command executed on cloud resources
```
### 智能体角色与权限
1. **Monitor Agent：** 对指标拥有只读权限。评估系统健康状况。
2. **Diagnosis Agent：** 对日志拥有只读权限。使用 `fetch_logs` MCP 工具。
3. **Action Agent：** 提出附带理由和风险等级的修复计划。
4. **Security Agent：** 把关者。检查策略并对变更性操作实施 human-in-the-loop 阻断。
## 3. 自定义 Model Context Protocol (MCP) Server
系统集成了一个使用 **FastMCP** 构建的自定义 MCP server，向智能体公开以下工具：
### 只读工具（低风险）
- `fetch_metrics(service_name: str)`：拉取 CPU、内存、延迟和 5xx 错误统计信息。
- `fetch_logs(service_name: str, tail_lines: int)`：拉取用于事件诊断的日志流。
### 修复工具（中/高风险）
- `restart_service(service_name: str)`：重启 container/instance 进程。
- `rollback_deployment(service_name: str, target_version: str)`：回滚到之前的稳定版本。
- `scale_resource(service_name: str, desired_count: int)`：更新活跃 instance 的 replica 数量。
## 4. Kaggle 课程核心概念与代码的映射
本项目展示了 5 个课程概念的实际应用：
| 核心概念 | 实现位置 | 描述 |
| :--- | :--- | :--- |
| **Multi-Agent System (ADK)** | [agents/definitions.py](file:///C:/Users/maaza/.gemini/antigravity/scratch/devops-guardian/agents/definitions.py) | 使用 `google.adk.agents.llm_agent.Agent` 构建的 Monitor、Diagnosis、Action 和 Security 智能体。 |
| **MCP Server** | [mcp_server/server.py](file:///C:/Users/maaza/.gemini/antigravity/scratch/devops-guardian/mcp_server/server.py) | Python FastMCP server，向 LLM 客户端公开指标、日志和修复 API。 |
| **Security Features** | [agents/orchestrator.py](file:///C:/Users/maaza/.gemini/antigravity/scratch/devops-guardian/agents/orchestrator.py#L90-L120) | Human-in-the-loop 验证门。所有变更性操作在被手动通过 CLI 签字确认前都会被阻断。 |
| **Agent Skills (CLI)** | [cli/guardian.py](file:///C:/Users/maaza/.gemini/antigravity/scratch/devops-guardian/cli/guardian.py) | 样式化的 Click CLI，公开 `status`、`diagnose` 和 `approve` 入口点。 |
| **Deployability** | `Dockerfile` & Mock Fallbacks | Docker 就绪的包结构。包含在缺少 API 密钥时的高保真 mock 回退机制。 |
## 5. 快速入门与设置说明
### 前置条件
- Python 3.10+（已在 Python 3.14 上测试）
- Pip
### 安装
1. 克隆或打开项目文件夹。
2. 安装依赖：
pip install -r requirements.txt
3. 将 `.env.example` 文件复制为 `.env`：
copy .env.example .env
4. （可选）提供您的 Gemini API 密钥：
GEMINI_API_KEY=AIzaSy...
*注意：如果未提供 API 密钥，系统将自动以高保真 Mock Mode 运行，并显示完全相同的追踪和执行输出，以便用于演示。*
## 6. 运行项目
您可以通过三种方式与 DevOps Guardian 交互：Web 仪表盘（推荐）、CLI 或自动化 Demo 脚本。
### 1. Web 仪表盘（推荐）
启动现代 Web 仪表盘（FastAPI 后端 + Vanilla JS 前端）：
```
uvicorn web_api:app --reload
```
然后，在您的 Web 浏览器中打开 `http://localhost:8000`。您可以点击“Diagnose Service”来触发多智能体流程，并通过 UI 与 Human-in-the-Loop 安全门进行交互。
### 2. Command Line Interface (CLI)
使用 CLI 检查状态或手动诊断服务：
```
# 检查系统状态
python -m cli.guardian status
# 为 service 触发 diagnostics
python -m cli.guardian diagnose --service web-api
# 批准待处理的 remediation action
python -m cli.guardian approve --action-id ACT-123456
```
### 3. 自动化 Demo 模拟
运行模拟的宕机事件，以观察智能体如何自动进行交互：
```
python -m demo.run_demo
```
## Kaggle Capstone 项目 (Agents for Business)
本项目是为 **AI Agents: Intensive Vibe Coding Capstone Project (July 2026)** 开发的。
**赛道：** Agents for Business
**展示的核心功能：**
- **Multi-Agent Systems：** 使用 Agent Development Kit (ADK) 协调四个专门的智能体。
- **MCP Servers：** 一个 FastMCP server 提供外部工具（`fetch_logs`、`scale_resource` 等）。
- **Agent Skills & Edge Cases：** 智能体拥有明确的指令来处理指标缺失和日志结果不明确的情况。
- **Security Features：** 专门的 Security Agent 会阻断高风险的变更性操作，强制执行 Human-in-the-Loop (HITL) 审批门。
- **Web Interface：** FastAPI 后端和现代原生 JS 前端提供了直观的管理仪表盘。
## 7. 运行端到端模拟 Demo
要通过一条命令自动查看整个生命周期的运行情况，请执行：
```
python demo/run_demo.py
```
这将执行初始状态检查，运行多智能体诊断，捕获安全阻断，批准操作，并验证成功的解决方案。
标签：AIOps, Google ADK, 事故响应, 多智能体, 自动化运维, 请求拦截, 逆向工具