# 🚨 Incident Response Agent
## 📋 目录
- [概述](#overview)
- [功能](#features)
- [团队](#team)
- [架构](#architecture)
- [使用的技术](#technologies-used)
- [前置条件](#prerequisites)
- [安装](#installation)
- [配置](#configuration)
- [运行应用程序](#running-the-application)
- [API 文档](#api-documentation)
- [项目结构](#project-structure)
- [演示](#demo)
- [链接](#links)
- [贡献](#contributing)
- [许可证](#license)
## 概述
**Incident Response Agent** 是一个由 AI 驱动的系统，旨在帮助 DevOps 和 SRE 团队快速诊断和解决生产事故。它利用 **Hindsight** 进行持久化内存存储，并利用 **cascadeflow** 进行智能模型路由，使其能够从过去的事故中学习并提供准确的、具备上下文感知能力的诊断。
### 工作原理
当工程师报告事故时，Agent 会：
1. 使用语义搜索**搜索其内存**以查找类似的历史事故
2. **检索最相关的**事故详情
3. **生成结构化诊断**，包括根本原因和解决步骤
4. 根据复杂度将查询**路由到最优的** LLM 模型
5. 通过存储新的事故数据从交互中**学习**
## 功能
### 🧠 持久化内存
- 存储每个事故的完整上下文（症状、根本原因、解决方案）
- 使用 **Hindsight** 的语义搜索来查找类似事故
- 自动从事故中提取实体、关系和事实
- 内存跨会话持久化，实现持续学习
### 💰 智能模型路由
- 使用 **cascadeflow** 将查询路由到最优的 LLM
- 简单查询 → 便宜、快速的模型
- 复杂查询 → 强大、具备推理能力的模型
- 在 LLM API 成本上**节省 40-85%**
### 🚀 快速且响应迅速
- 路由决策的额外开销低于 5ms
- 实时流式响应
- API 优先设计，便于集成
### 🎯 结构化诊断
- **历史事故摘要** - 过去发生了什么
- **根本原因** - 导致事故的原因
- **恢复步骤** - 之前是如何解决的
- **当前建议** - 现在该怎么做
### 📊 精美 UI
- 简洁、现代的仪表板
- 带有加载状态的实时分析
- 带有颜色区分的置信度指示器
- 一键快速测试警报
## 👥 Team TwinSparks 🔥
| 角色 | 姓名 | GitHub |
|------|------|--------|
| **团队负责人 / 开发者** | Revathi | [@revathi](https://github.com/revathi) |
| **开发者** | Rattishkumar SS | [@rattishkumar](https://github.com/rattishkumar) |
## 架构
```
┌─────────────────────────────────────────────────────────────────────┐
│ USER INTERFACE │
│ (HTML/CSS/JavaScript) │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ FASTAPI BACKEND │
│ (app/api.py) │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ INCIDENT AGENT (LangGraph) │
│ (app/agent.py) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌───────────────────────┐ │
│ │ Intake │───▶│ Memory │───▶│ Investigate │ │
│ │ Node │ │ Node │ │ Node │ │
│ └─────────────┘ └─────────────┘ └───────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Response Generation │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐
│ HINDSIGHT │ │ cascadeflow │ │ GROQ / LLM │
│ MEMORY │ │ ROUTING │ │ PROVIDER │
└─────────────────┘ └─────────────────┘ └─────────────────────┘
```
## 使用的技术
| 技术 | 用途 |
|------------|---------|
| **FastAPI** | 后端 API 框架 |
| **LangGraph** | Agent 编排和工作流管理 |
| **Hindsight Cloud** | 持久化内存存储和语义搜索 |
| **cascadeflow** | 智能模型路由和成本优化 |
| **Groq** | 快速 LLM 推理，提供慷慨的免费额度 |
| **HTML/CSS/JS** | 前端 UI |
### 使用的 LLM 模型
| 模型 | 提供商 | 成本 | 用例 |
|-------|----------|------|----------|
| qwen/qwen3-32b | Groq | $0.000375/token | 简单查询，首次尝试 |
| llama-3.3-70b-versatile | Groq | $0.00562/token | 复杂推理，兜底方案 |
## 前置条件
- **Python 3.10+**
- **Groq API Key** (免费) - [从 Groq 控制台获取](https://console.groq.com)
- **Hindsight Cloud API Key** - [注册](https://ui.hindsight.vectorize.io) (使用代码 `MEMHACK625` 可获得 $50 免费额度)
- **Git** (用于克隆)
- **VS Code** (推荐) 或任何文本编辑器
## 安装
### 1. 克隆仓库
```
git clone https://github.com/Revathi2006/incident-response-agent.git
cd incident-response-agent
```
### 2. 创建并激活虚拟环境
```
# Windows
python -m venv venv
venv\Scripts\activate
# macOS/Linux
python3 -m venv venv
source venv/bin/activate
```
### 3. 安装依赖项
```
pip install -r requirements.txt
```
### 4. 设置环境变量
在项目根目录中创建一个 `.env` 文件：
```
# .env
HINDSIGHT_API_KEY=your-hindsight-api-key-here
GROQ_API_KEY=your-groq-api-key-here
```
## 配置
### 环境变量
| 变量 | 描述 | 是否必需 |
|----------|-------------|----------|
| `HINDSIGHT_API_KEY` | 你的 Hindsight Cloud API key | ✅ 是 |
| `GROQ_API_KEY` | 你的 Groq API key | ✅ 是 |
| `HINDSIGHT_URL` | Hindsight API endpoint (默认: api.hindsight.vectorize.io) | ❌ 否 |
### 事故数据
事故存储在 `data/incidents.json` 中。每个事故应包含：
```
{
"incident_id": "INC-001",
"title": "Payment API complete outage",
"symptoms": "All payment requests failing with HTTP 503",
"root_cause": "Database connection pool exhausted",
"resolution": "Restarted PostgreSQL, increased pool size",
"affected_service": "Payment Gateway",
"severity": "Critical",
"duration_minutes": 45,
"detection_method": "AlertManager"
}
```
## 运行应用程序
### 加载事故数据的命令
```
python data/load_data.py
```
**预期输出：**
```
📥 Loading 10 incidents from data/incidents.json
🗑️ Deleted old bank
📥 Storing incidents as JSON...
✅ Stored INC-001
✅ Stored INC-002
✅ Stored INC-003
...
✅ Loaded 10 incidents as JSON!
```
### 运行服务器的命令
```
python run.py
```
**预期输出：**
```
🚀 Starting Incident Response Agent...
==================================================
✅ API keys found
📡 Starting FastAPI server at http://localhost:8000
📚 API Docs at http://localhost:8000/docs
==================================================
INFO: Uvicorn running on http://0.0.0.0:8000
```
### 测试 API 的命令
#### 健康检查
```
curl http://localhost:8000/health
```
#### 分析事故 (PowerShell)
```
$body = @{alert="Payment service is returning 503 errors"} | ConvertTo-Json
Invoke-RestMethod -Uri "http://localhost:8000/incident" -Method POST -Body $body -ContentType "application/json"
```
#### 分析事故 (curl)
```
curl -X POST "http://localhost:8000/incident" \
-H "Content-Type: application/json" \
-d '{"alert": "Payment service is returning 503 errors"}'
```
### 打开 UI
1. 在浏览器中打开 `index.html`
- 双击该文件，或
- 使用 VS Code Live Server 扩展，或
- 运行 `python -m http.server 8080` 并访问 `http://localhost:8080`
## API 文档
### Endpoints
| 方法 | Endpoint | 描述 |
|--------|----------|-------------|
| `GET` | `/` | 包含状态的根 endpoint |
| `GET` | `/health` | 详细健康检查 |
| `POST` | `/incident` | 分析事故警报 |
### POST `/incident`
**请求体：**
```
{
"alert": "Payment service is returning 503 errors"
}
```
**响应：**
```
{
"diagnosis": "This incident closely matches a previously resolved incident...",
"model_used": "llama-3.3-70b-versatile",
"cost": 0.00024,
"confidence": "High",
"root_cause": "Database connection pool exhausted...",
"resolution_steps": [
"Restarted PostgreSQL",
"Increased connection pool size",
"Added connection timeout"
]
}
```
### Swagger 文档
访问交互式 API 文档：`http://localhost:8000/docs`
## 项目结构
```
incident-response-agent/
│
├── app/
│ ├── __init__.py
│ ├── agent.py # Core agent logic
│ ├── api.py # FastAPI endpoints
│ ├── config.py # Configuration settings
│ └── models.py # Pydantic models
│
├── data/
│ ├── incidents.json # Incident dataset
│ └── load_data.py # Data loading script
│
├── docs/
│ └── README.md # Project documentation
│
├── .env # Environment variables (don't commit!)
├── .env.example # Example environment file
├── .gitignore # Git ignore file
├── index.html # Beautiful UI
├── LICENSE # MIT License
├── requirements.txt # Python dependencies
├── run.py # Application entry point
└── test_cascade.py # Test script
```
## 演示
### 快速演示步骤
1. **加载数据：**
python data/load_data.py
2. **启动服务器：**
python run.py
3. **打开 UI：**
- 在浏览器中打开 `index.html`
4. **输入事故：**
- 输入："Payment service is returning 503 errors"
- 或点击一个快速测试按钮
5. **查看诊断：**
- Agent 分析事故
- 显示类似的历史事故
- 提供根本原因和解决步骤
- 显示置信度和成本
### 演示视频
[](https://youtu.be/your-demo-video-link)
**链接：** [https://youtu.be/your-demo-video-link](https://youtu.be/your-demo-video-link)
## 链接
### 项目链接
- **GitHub 仓库**：[https://github.com/Revathi2006/incident-response-agent](https://github.com/Revathi2006/incident-response-agent)
- **演示视频**：[https://youtu.be/your-demo-video-link](https://youtu.be/your-demo-video-link)
- **文章**：[https://medium.com/@Revathi2006/incident-response-agent](https://medium.com/@Revathi2006/incident-response-agent)
- **LinkedIn 帖子**：[https://linkedin.com/posts/Revathi2006/incident-response-agent](https://linkedin.com/posts/Revathi2006/incident-response-agent)
- **Reddit 帖子**：[https://reddit.com/r/your-subreddit/comments/incident-response-agent](https://reddit.com/r/your-subreddit/comments/incident-response-agent)
### 技术链接
- **Hindsight**：[https://github.com/vectorize-io/hindsight](https://github.com/vectorize-io/hindsight)
- **cascadeflow**：[https://github.com/lemony-ai/cascadeflow](https://github.com/lemony-ai/cascadeflow)
- **Groq**：[https://console.groq.com](https://console.groq.com)
## 故障排除
### 常见问题
| 问题 | 解决方案 |
|-------|----------|
| `ModuleNotFoundError` | 运行 `pip install -r requirements.txt` |
| `Hindsight API key invalid` | 检查 `.env` 文件，确保密钥正确 |
| `Port 8000 in use` | 将 `run.py` 中的端口更改为 8001 |
| `No incidents found` | 运行 `python data/load_data.py` |
| 输出中包含 `
` 标签 | 已更新的 `agent.py` 包含清理逻辑 |
### 获取帮助
- [Hindsight 文档](https://hindsight.vectorize.io/)
- [cascadeflow 文档](https://docs.cascadeflow.ai/)
- [Groq 控制台](https://console.groq.com)
## 许可证
MIT 许可证 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
## 致谢
- 使用 [Hindsight](https://github.com/vectorize-io/hindsight) 构建内存
- 由 [cascadeflow](https://github.com/lemony-ai/cascadeflow) 提供路由支持
- 通过 [Groq](https://groq.com/) 进行 LLM 推理
## 👥 Team TwinSparks 🔥
| 角色 | 姓名 | GitHub |
|------|------|--------|
| **团队负责人 / 开发者** | Revathi | [@Revathi2006](https://github.com/revathi) |
| **开发者** | Rattishkumar SS | [@Rattishaids](https://github.com/rattishkumar) |
由 Team TwinSparks 🔥 用 ❤️ 制作
专为 Hindsight x cascadeflow 黑客松打造