pragna-y/incidentops-ai
GitHub: pragna-y/incidentops-ai
一款使用 Google ADK 和 MCP 构建的多智能体 AI 系统，通过日志解析、指标关联、安全脱敏和模拟响应来协助 SRE 团队自主进行生产事件的分诊与处置。
Stars: 0 | Forks: 0
# IncidentOps AI
**自主事件分诊与响应 Agent**
*作品集 / 简历项目 — 首席软件工程师与 AI 系统架构师*
[](https://python.org)
[](https://google.github.io/adk-docs/)
[](https://modelcontextprotocol.io)
[](LICENSE)
## 概述
IncidentOps AI 是一个生产级的多 Agent 系统，旨在协助站点可靠性工程师 (SRE) 应对生产事件。该项目旨在展示高级软件架构技能：多 Agent AI 编排、安全工程、基于协议的设计以及全栈可部署性。
```
Production Log File
│
▼
┌─────────────────┐
│ Security Gate │ Offline regex redaction — zero PII reaches the LLM
│ (OfflineRedactor)│
└────────┬────────┘
│
▼
┌─────────────────┐
│ Log Parser │ Structures events, detects anomalies
└────────┬────────┘
│
▼
┌─────────────────┐
│ Metric Correlator│ Maps scenario to infrastructure metrics snapshot
└────────┬────────┘
│
▼
┌────────────────────────────────────────────┐
│ Google ADK Agent Pipeline │
│ │
│ ┌──────────┐ ┌────────────┐ │
│ │ Triage │ │ Researcher │ ← MCP Server│
│ │ Agent │──▶│ Agent │ (Runbooks)│
│ └──────────┘ └─────┬──────┘ │
│ │ │
│ ┌──────────┐ ┌──────▼──────┐ │
│ │Reflector │◀──│ Planner │ │
│ │ Agent │ │ Agent │ │
│ └──────────┘ └─────────────┘ │
└──────────────────────┬─────────────────────┘
│
▼
⚠ Human Approval Gate (HITL)
│
▼
Simulation Engine
(Dry-run — no real changes)
```
## 展示的核心技能
| 技能 | 实现方式 |
|-------|----------------|
| **多 Agent AI** | 4 个 Google ADK `LlmAgent` 实例，具备共享状态和工具调用 |
| **MCP (Model Context Protocol)** | 使用 FastMCP server 暴露 SRE runbook；通过 `mcp` client SDK 采用 stdio 传输 |
| **安全工程** | 离线 PII 脱敏网关（7 种规则类型）— LLM 永远不会接触到原始敏感数据 |
| **整洁架构** | 分层设计：domain → services → skills → agents → infra；零循环导入 |
| **基于协议的设计** | `RedactorProtocol` 允许无缝切入 Google Cloud DLP，而无需修改 agent 代码 |
| **Human-in-the-Loop (HITL)** | 在任何模拟之前，由 `ApprovalStatus` enum 锁定的显式 CLI 审批网关 |
| **自我反思** | 专属的 `ReflectorAgent` 审视计划、调整置信度并标记升级 |
| **可部署性** | 包含两个 Dockerfile + Docker Compose；完全可复现，无需云配置 |
| **测试** | 55 个测试（42 个单元测试 + 13 个集成测试）— 全部通过，无需 API key |
## 功能
| 功能 | 描述 |
|---------|-------------|
| **安全脱敏** | 离线 regex 引擎在任何 LLM 调用之前，对 IP、email、token、JWT 和 API key 进行脱敏 |
| **日志解析** | 将原始日志解析为类型化事件，并具备基于关键字检测异常的能力 |
| **指标关联** | 将事件映射到基础设施指标（CPU、内存、DB pool、JVM heap 等） |
| **MCP Runbook Server** | FastMCP server 通过 stdio/SSE 传输将 SRE runbook 作为工具暴露出来 |
| **多 Agent Pipeline** | 4 个 Google ADK agent（Triage → Researcher → Planner → Reflector） |
| **Human-in-the-Loop** | 模拟运行前需要显式的 CLI 审批 |
| **模拟引擎** | 演练报告显示将要执行的操作 — 不会对真实基础设施进行任何更改 |
| **审计追踪** | 每个 agent 操作都会记录在带有时间戳的 `IncidentState` 中 |
| **Dockerized** | App + MCP server 各自拥有专属的 Dockerfile + Compose 文件 |
## 快速开始
### 前置条件
- Python 3.11+
- [Google API Key](https://aistudio.google.com/apikey) *（仅用于 `analyze` 命令）*
### 安装
```
# 克隆 / 解压项目
cd incidentops-ai
# 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate # Windows
source .venv/bin/activate # Linux/macOS
# 安装所有依赖
pip install -e ".[dev]"
# 配置 API key（仅 analyze 命令需要）
copy .env.example .env
# 编辑 .env → 设置 GOOGLE_API_KEY=your-key-here
```
### 命令
#### `triage` — 安全 + 解析流水线 *（无需 API key）*
对日志进行脱敏，检测异常，关联指标，并通过 MCP 获取 runbook。
```
incidentops triage --log sample_logs/db_pool_exhaustion.log
incidentops triage --log sample_logs/cpu_spike.log --save
incidentops triage --log sample_logs/memory_leak.log --no-preview
```
#### `analyze` — 完整多 Agent 流水线 *（需要 API key）*
运行所有 4 个 ADK agent → 展示建议 → 人工审批 → 模拟运行。
```
set GOOGLE_API_KEY=your-key-here
incidentops analyze --log sample_logs/db_pool_exhaustion.log
incidentops analyze --log sample_logs/memory_leak.log --save-report
```
## 架构
### 项目布局
```
incidentops-ai/
├── src/
│ ├── config.py # Pydantic settings (env var overrides)
│ ├── core/
│ │ ├── entities.py # Pure domain models — no infra imports
│ │ ├── interfaces.py # RedactorProtocol (DLP plug-in ready)
│ │ └── state.py # IncidentState — shared agent working memory
│ ├── services/
│ │ ├── redactor.py # OfflineRedactor (7 rule types)
│ │ ├── parser.py # LogParser + anomaly detection
│ │ └── correlator.py # MetricCorrelator (scenario → metrics)
│ ├── skills/ # ADK agent tool functions (plain Python)
│ │ ├── log_tools.py # 6 tools — Triage Agent
│ │ ├── metric_tools.py # 2 tools — Triage Agent
│ │ ├── runbook_tools.py # 4 tools — Researcher Agent
│ │ └── simulation_tools.py # 6 tools — Planner + Reflector + Simulation
│ ├── agents/
│ │ └── orchestrator.py # IncidentOrchestrator (4-agent sequential pipeline)
│ └── infra/
│ ├── cli.py # Typer CLI (triage + analyze commands)
│ └── mcp_client.py # MCP client (stdio transport + local fallback)
├── mcp_servers/
│ └── runbook_server/
│ ├── server.py # FastMCP server (list/get/search tools)
│ └── data/ # 3 production-quality SRE runbooks (markdown)
├── sample_logs/ # 3 realistic incident log files
├── tests/
│ ├── unit/ # 42 redaction unit tests (no API key)
│ └── integration/ # 13 end-to-end pipeline tests (no API key)
├── docker/
│ ├── app.Dockerfile
│ └── mcp.Dockerfile
├── docker-compose.yml
└── pyproject.toml
```
### 关键设计决策
1. **安全至上** — `OfflineRedactor` 始终是第一道关卡。LLM 永远不会看到原始 PII。可通过 `RedactorProtocol` adapter 扩展至 Google Cloud DLP。
2. **纯领域模型** — `entities.py` 没有任何基础设施导入 — 完全可序列化，易于测试，且与框架无关。
3. **作为工作记忆的状态** — `IncidentState`（Pydantic model）是所有 agent 和流水线阶段之间传递的唯一事实来源。
4. **带本地兜底的 MCP** — 如果 MCP server 不可用，`RunbookClient` 会平滑回退到本地文件 — 演示始终可以离线进行。
5. **设计上的 HITL** — 模拟引擎在运行前会检查 `ApprovalStatus.APPROVED` — 该网关无法通过编程方式绕过。
6. **工具函数而非方法** — ADK 工具是纯 Python 函数，使其独立于 ADK 具备可测试性和可组合性。
## 运行测试
```
# 所有测试 — 不需要 API key
pytest tests/ -v
# 仅 Unit
pytest tests/unit/ -v
# 仅 Integration
pytest tests/integration/ -v
# 带 coverage 报告
pytest --cov=src --cov-report=term-missing
```
**当前结果：55/55 通过**
## Docker
```
# 构建并启动所有服务（MCP server + app）
docker compose up --build
# 运行 triage（不需要 API key）
docker compose run app triage --log sample_logs/db_pool_exhaustion.log
# 运行完整的多 agent 分析
docker compose run app analyze --log sample_logs/memory_leak.log
# 仅 MCP server（SSE transport 在端口 8090）
docker compose up mcp-server
```
## 事件示例
| 场景 | 日志文件 | 关键信号 |
|----------|----------|-------------|
| 数据库连接池耗尽 | `db_pool_exhaustion.log` | 100% 连接池使用率，JDBC 超时，重试风暴 |
| CPU 激增 | `cpu_spike.log` | 97% CPU，线程池饱和，89 错误/分钟 |
| 内存泄漏 | `memory_leak.log` | JVM heap 达到 3.7/4.0 GB，GC 停顿 >2s，OOMKilled |
## 技术栈
- **语言：** Python 3.11+
- **AI 框架：** Google ADK (`google-adk`) — `LlmAgent`, `Runner`, `InMemorySessionService`
- **LLM：** Gemini 2.0 Flash（通过 `google-genai`）
- **MCP：** `mcp` SDK — FastMCP server（stdio + SSE 传输）
- **校验：** Pydantic v2, pydantic-settings
- **CLI：** Typer + Rich（面板、进度旋转动画、表格）
- **测试：** pytest, pytest-cov, pytest-anyio
- **容器：** Docker + Docker Compose
## 许可证
MIT — 见 [LICENSE](LICENSE)
标签：DLL 劫持, Google ADK, MCP, PyRIT, Python, 多智能体系统, 大语言模型, 无后门, 智能运维, 自动化分析, 请求拦截, 跨站脚本