Praneeth0910/incident-response-env
GitHub: Praneeth0910/incident-response-env
这是一个符合 OpenEnv 标准的强化学习基准环境，用于测试 LLM 智能体在模拟微服务故障中担任值班 SRE 进行诊断和修复的能力。
Stars: 2 | Forks: 1
## title: Incident Response Env
emoji: 🚨
colorFrom: red
colorTo: blue
sdk: docker
pinned: false
license: apache-2.0
short_description: LLM agents act as on-call SREs.
"}
{"action_type": "check_metrics", "target": ""}
{"action_type": "check_health", "target": ""}
{"action_type": "run_db_query", "target": "postgres-db"}
{"action_type": "restart_service", "target": ""}
{"action_type": "rollback_deployment", "target": ""}
{"action_type": "declare_rca", "target": ""}
```
**Available services:** `api-gateway` · `auth-service` · `order-service` · `notification-service` · `redis-cache` · `postgres-db`
## Observation space
每个动作都会返回丰富的观察结果：
| Field | Type | Description |
|---|---|---|
| `message` | string | 当前观察文本 |
| `step` | int | 当前步数 |
| `done` | bool | Episode 结束 |
| `alert` | string | 原始事故警报 |
| `metrics` | object | 服务指标（如果已请求） |
## 📋 Task Suite
**14 个精心设计的事故场景**，难度递增，测试不同的故障模式和诊断推理模式：
| Task | Difficulty | Max Steps | Description |
|---|---|---|---|
| `task_cpu_spike` | Easy | 10 | Auth service CPU 热循环 |
| `task_db_connection_leak` | Medium | 15 | Order-service 连接池耗尽 |
| `task_canary_poison` | Hard | 20 | Canary 部署剥离了 auth headers |
*[在 [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md#task-definitions) 中查看完整任务列表]*
### 🟡 Sample Scenario: Bad Deployment Cascade (Red Herring)
`order-service` 上的错误部署级联导致 `auth-service` 看起来像是坏掉了——这是一个故意的误导性线索。日志显示缺少环境变量。正确的修复方案是 **rollback**。
**Tests:** 对误导性线索的抵抗力，多服务关联。
## 🔬 The Simulated Microservices System
智能体调查一个包含 6 个服务的生产技术栈，由 `api-gateway`（始终是受害者）、`auth-service`、`order-service`、`notification-service`、`redis-cache` 和 `postgres-db` 组成。
**Key design principle:** 网关**始终是受害者，绝不是根本原因**。这迫使智能体向上游追溯因果关系。
## Reward function
- `+0.05` 到 `+0.12` —— 发现相关证据
- `+0.005` —— 冗余动作（已检查过）
- `+0.30` —— 正确干预（重启/回滚）
- `+0.05` —— 重启了错误的服务
- `+0.01` —— 回滚了错误的服务
- `+0.50` + 时间奖励 + 证据奖励 —— 声明了正确的 RCA
- `+0.001` —— 错误的 RCA
- 累计值严格限制在 `[0.01, 0.99]`
## 📊 Baseline Performance
| Model | task_easy | task_medium | task_hard | Avg Score | Solved |
|---|---|---|---|---|---|
| Random agent | ~0.15 | ~0.08 | ~0.04 | ~0.09 | 0/3 |
| Qwen2.5-72B | ~0.75 | ~0.60 | ~0.45 | ~0.60 | 2/3 |
| *Human expert* | *~0.95* | *~0.90* | *~0.85* | *~0.90* | *3/3* |
**在 `task_hard` 上的人机差距为 0.40 分。** 弥合这一差距需要真正的顺序推理，而不是模式匹配。
## 🤖 Agent Skill Taxonomy
该基准将智能体清晰地分为四个能力等级：
| Level | Score | Behavior |
|---|---|---|
| **0 — Random Walker** | 0.00–0.15 | 重复相同的动作，从不声明 RCA |
| **1 — Symptom Chaser** | 0.15–0.40 | 读取网关日志，然后穷尽地扩散到所有服务 |
| **2 — Structured Investigator** | 0.40–0.70 | 找到正确的服务，应用错误的修复类型或声明太晚 |
| **3 — Expert SRE** | 0.70–1.00 | 3 步假设，佐证证据，正确修复，时间奖励 |
Level 2 和 Level 3 之间的差距在于**对误导性线索的抵抗力**——这是该基准中最具区分度的信号。
## 📊 Getting Started with Baselines
该环境附带 `inference.py`，这是一个使用思维链提示的参考基准智能体。
### Supported LLM Endpoints
该基准适用于任何兼容 OpenAI 的端点。**OpenAI (GPT-4o) 是推荐的基准。**
#### 🌟 **Quick Start with OpenAI (Recommended)**
**Bash:**
```
export API_BASE_URL="https://api.openai.com/v1"
export API_KEY="sk_YOUR_OPENAI_KEY"
export MODEL_NAME="gpt-4o"
python inference.py
```
**PowerShell:**
```
$env:API_BASE_URL="https://api.openai.com/v1"
$env:API_KEY="sk_YOUR_OPENAI_KEY"
$env:MODEL_NAME="gpt-4o"
python inference.py
```
#### Other Supported Providers
要使用其他提供商，请相应更改 `API_BASE_URL`、`API_KEY` 和 `MODEL_NAME`。
| Provider | Endpoint | Model Example | Setup |
|---|---|---|---|
| **OpenAI** ⭐ | `https://api.openai.com/v1` | `gpt-4o`, `gpt-4-turbo` | [Get API key](https://platform.openai.com/api/keys) |
| **Anthropic (Claude)** | 通过 LiteLLM 代理 | `claude-3-opus` | [Install LiteLLM](https://docs.litellm.ai/docs/) |
| **HuggingFace Inference** | `https://api-inference.huggingface.co/v1` | `meta-llama/Llama-2-70b` | [Get token](https://huggingface.co/settings/tokens) |
| **Together AI** | `https://api.together.xyz/v1` | `mistralai/Mixtral-8x7B` | [Get API key](https://together.ai) |
| **Ollama (local)** | `http://localhost:11434/v1` | 任何本地模型 | [Install Ollama](https://ollama.ai) |
## 📈 Interpreting Results
### Score Breakdown
每个任务返回一个 `[0.0, 1.0]` 范围内的分数。分数越高越好。分数计算如下：
$$\text{score} = \text{clamp}(0.01, \text{evidence\_bonus} + \text{fix\_bonus} + \text{rca\_bonus} + \text{time\_bonus}, 0.99)$$
**详细分解：**
| Component | Impact | Notes |
|---|---|---|
| **Evidence Bonus** | ±0.30 | 每种唯一的证据类型（日志、指标、健康检查、查询）+0.05–0.12 |
| **Fix Bonus** | +0.30 | 仅当在声明 RCA **之前**对正确的服务进行重启/回滚时给予 |
| **RCA Bonus** | +0.50 | 仅当声明的 RCA 与真实情况一致时授予 |
| **Time Bonus** | 0 到 −0.15 | 从第 10 步开始线性惩罚；在步数预算限制时达到 −0.15 |
**示例：**
- **完美解决 (0.95)：** 找到所有 4 种证据类型，应用正确的修复，在第 8 步声明 RCA
- Evidence: +0.12 + 0.10 + 0.08 + 0.05 = +0.35
- Fix: +0.30
- RCA: +0.50
- Time: −0.02 (第 8 步 vs 限制 10)
- **Total: 0.95**
- **迟滞但正确 (0.80)：** 找到 3 种证据类型，在第 14 步正确修复，在第 16 步声明 RCA
- Evidence: +0.12 + 0.10 + 0.08 = +0.30
- Fix: +0.30
- RCA: +0.50
- Time: −0.30 (第 16 步 vs 限制 15)
- **Total: 0.80**
- **修复了错误的服务 (0.55)：** 重启 auth-service（误导性线索），然后声明正确的 RCA
- Evidence: +0.30
- Fix: +0.05 (错误的服务，少量加分)
- RCA: +0.50
- Time: 0
- **Total: 0.85** —— 但被限制或应用了惩罚
### Interpreting the Leaderboard
排行榜按**所有三个任务的平均分数**对智能体进行排名：
```
{
"agent": "Qwen2.5-72B-Instruct",
"scores": {
"task_easy": 0.92,
"task_medium": 0.68,
"task_hard": 0.41
},
"average": 0.67,
"solved": 2, // tasks with score >= 0.70
"rank": 5
}
```
**Performance tiers:**
- **0.85+:** Expert SRE —— 罕见；需要强大的长视界规划
- **0.70–0.85:** Competent investigator —— 解决大多数简单/中等任务
- **0.40–0.70:** Symptom chaser —— 找到正确的服务但修复或时机错误
- **0.15–0.40:** Red herring victim —— 穷尽所有服务而无重点
- **0.00–0.15:** Random walker —— 没有连贯的策略
### Common Failure Patterns
- **无重点的穷尽搜索：** 在声明 RCA 之前检查所有 6 个服务（高时间惩罚）
- **误导性线索陷阱：** 在 `task_medium` 上修复 auth-service 而不是 order-service（错误修复奖励，严重惩罚）
- **过早的 RCA：** 在第 4 步仅用 1 种证据类型声明（RCA 奖励低，但无时间惩罚 —— 仍可得分 0.60–0.70）
- **缺少证据：** 找到正确的服务但从未收集支持性日志/指标（证据奖励封顶，仅 RCA 奖励；总计约 0.70）
## 🔗 Integration and CI/CD
将基准嵌入 GitHub Actions，以便在每个 PR 上自动测试你的智能体。
```
# .github/workflows/benchmark.yml
name: Benchmark Agent
on: [pull_request]
jobs:
benchmark:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with: { python-version: '3.11' }
- run: pip install -e .
- env:
API_BASE_URL: ${{ secrets.OPENAI_BASE_URL }}
API_KEY: ${{ secrets.OPENAI_API_KEY }}
MODEL_NAME: gpt-4o
run: |
uvicorn server.app:app --host 0.0.0.0 --port 7860 &
sleep 3
python inference.py > benchmark.json
```
## 🚀 Quick Start & Benchmarking
### 1. Local Setup
克隆仓库并启动 FastAPI + Gradio 服务器：
**Bash/PowerShell:**
```
git clone https://github.com/Praneeth0910/incident-response-env
cd incident-response-env
pip install -e .
uvicorn server.app:app --host 0.0.0.0 --port 7860
```
*打开 [http://localhost:7860](http://localhost:7860/dashboard) 进行手动操作。*
### 2. Docker (Production)
```
docker-compose up --build
```
*端口映射请参见 `docker-compose.yml`。*
### 3. Run the LLM Agent Baseline
配置环境变量并运行 `inference.py`。
**Unix / Bash:**
```
export API_BASE_URL="https://api.openai.com/v1"
export API_KEY="sk_YOUR_OPENAI_KEY"
export MODEL_NAME="gpt-4o"
python inference.py
```
**Windows / PowerShell:**
```
$env:API_BASE_URL="https://api.openai.com/v1"
$env:API_KEY="sk_YOUR_OPENAI_KEY"
$env:MODEL_NAME="gpt-4o"
python inference.py
```
### 4. Direct API Usage (Programmatic)
直接发送 REST 命令以评估自定义智能体，无需 `inference.py`：
```
# Start an episode
curl -X POST http://localhost:7860/reset -H "Content-Type: application/json" -d '{"task_id": "task_easy"}'
# Take step
curl -X POST http://localhost:7860/step -H "Content-Type: application/json" -d '{"action_type": "read_logs", "target": "api-gateway"}'
# Get score
curl http://localhost:7860/grade
```
## 🏗️ Architecture
```
┌─────────────────────────────────┐
│ Gradio Web Dashboard │
└────────────┬────────────────────┘
▼
┌─────────────────────────────────┐
│ FastAPI Server (port 7860) │
│ /reset, /step, /grade, /tasks │
└────────────┬────────────────────┘
▼
┌─────────────────────────────────┐
│ IncidentResponseEnv │
│ (State Machine + Pydantic) │
└─────────────────────────────────┘
```
## 📁 Repository Structure
```
incident-response-env/
├── environment.py # Core RL environment — state machine, rewards
├── models.py # Pydantic schemas (Action, Observation, Reward)
├── inference.py # LLM agent baseline + OpenEnv-compliant runner
├── server/
│ ├── app.py # FastAPI application (uvicorn entry point)
│ ├── dashboard_impl.py # Gradio UI — interactive episode runner
│ └── gradio_app.py # Standalone Gradio launcher
├── docs/
│ ├── AGENT.md # Full agent operating manual
│ ├── ENVIRONMENT.md # Complete environment specification
│ ├── BENCHMARK.md # Multi-model benchmarking guide
│ ├── REWARDS.md # Reward engineering deep dive
│ └── SKILLS.md # Agent capability taxonomy + prompt engineering
├── Dockerfile # Production container
├── start.sh # Container startup (server + inference)
├── openenv.yaml # OpenEnv specification manifest
└── README.md # This file
```
## 🔌 REST API
| Endpoint | Method | Description |
|---|---|---|
| `/health` | GET | 健康检查 |
| `/reset` | POST | 开始一个新的 episode (`{"task_id": "task_easy"}`) |
| `/step` | POST | 执行一个动作 |
| `/grade` | GET | 获取最终 episode 分数 `[0.0, 1.0]` |
| `/state` | GET | 真实状态（仅调试 —— 会泄露答案） |
| `/tasks` | GET | 列出所有可用任务 |
**Example session (Bash):**
```
# Start episode
curl -X POST http://localhost:7860/reset \
-H "Content-Type: application/json" \
-d '{"task_id": "task_hard"}'
# Take action
curl -X POST http://localhost:7860/step \
-H "Content-Type: application/json" \
-d '{"action_type": "read_logs", "target": "redis-cache"}'
# Get score
curl http://localhost:7860/grade
```
**Example session (PowerShell):**
```
# Start episode
$body = @{task_id = "task_hard"} | ConvertTo-Json
Invoke-WebRequest -Uri "http://localhost:7860/reset" -Method POST -ContentType "application/json" -Body $body
# Take action
$body = @{action_type = "read_logs"; target = "redis-cache"} | ConvertTo-Json
Invoke-WebRequest -Uri "http://localhost:7860/step" -Method POST -ContentType "application/json" -Body $body
# Get score
Invoke-WebRequest http://localhost:7860/grade
```
## Real-World Impact
**谁将从解决此基准中受益？**
- **云提供商** (AWS, GCP, Azure) —— 自动化事故分类可将 MTTR 降低 60–80%
- **DevOps 团队** —— 值班工程师的 AI 副驾驶可减少警报疲劳
- **SRE 平台** (PagerDuty, OpsGenie, Datadog) —— 智能根本原因建议作为产品功能
- **AI 安全研究人员** —— 一个可复现的基准，用于测量智能体在部分可观测性下的因果推理能力
全球 Site Reliability Engineering 市场价值 **87 亿美元**（2024 年），并以 15% 的复合年增长率增长。自动化事故解决的每一个百分点的改进都直接转化为节省的工程工时和提升的服务可靠性。
## 📚 Documentation
| Document | Description |
|---|---|
| [AGENT.md](docs/AGENT.md) | 完整的智能体操作手册 —— 最佳策略、反模式、示例 episode |
| [ENVIRONMENT.md](docs/ENVIRONMENT.md) | 完整的 API 参考、任务定义、扩展环境 |
| [BENCHMARK.md](docs/BENCHMARK.md) | 多模型基准测试、支持的端点、结果解释 |
| [REWARDS.md](docs/REWARDS.md) | 奖励工程理念、调优指南、RL 训练技巧 |
| [SKILLS.md](docs/SKILLS.md) | 智能体技能分类、提示工程建议 |
## 🤝 Contributing
想要添加新的故障类型、任务或服务？请参阅 [ENVIRONMENT.md](docs/ENVIRONMENT.md#extending-the-environment) 了解扩展指南。
欢迎针对以下内容提交 Pull requests：
- 新的故障场景（网络分区、磁盘已满、证书过期）
- 额外的服务（消息队列、CDN、负载均衡器）
- 改进的基准智能体
- 多智能体协作诊断
## 📄 License
Apache 2.0 —— 可免费用于研究、商业用途和衍生作品。
# 🚨 Incident Response Environment
### *AI 成为你的值班工程师的基准*
[](https://openenv.dev)
[](https://huggingface.co/spaces/ZenkuIshigami09/incident-response-env)
[](LICENSE)
[](Dockerfile)
**一个符合 OpenEnv 标准的强化学习基准，LLM 智能体必须在其中诊断级联的微服务故障——就像真正的 Site Reliability Engineer 那样。**
[🎮 Live Demo](https://huggingface.co/spaces/ZenkuIshigami09/incident-response-env) · [📖 Environment Docs](docs/ENVIRONMENT.md) · [📊 Benchmark Guide](docs/BENCHMARK.md) · [🤖 Agent Guide](docs/AGENT.md)
# Production Incident Response Environment
一个符合 OpenEnv 标准的 RL 环境，LLM 智能体在其中担任值班 SRE，
在时间压力下调查模拟的微服务故障以确定根本原因。
## 为什么存在这个环境
每个在生产环境中运行软件的技术公司都会遇到事故。数据库变慢，API 开始抛出 500 错误，用户无法登录。值班工程师必须调查嘈杂、不完整的信号，并尽快确定根本原因。这个环境模拟的就是这个确切的任务。
## 🌍 为什么这个问题很重要
当生产环境宕机时，值班 SRE 会在凌晨 3 点收到寻呼机警报。他们只有几分钟——而不是几小时——来调查跨数十个微服务的嘈杂、不完整信号的级联，形成假设，应用正确的修复方案，并声明根本原因。**出错意味着停机时间延长、收入损失和用户流失。**
这不是一个已解决的问题。当前的 AI 系统无法在以下情况下可靠地执行顺序诊断推理：
- **部分可观测性** —— 你只能看到你查询的内容
- **主动欺骗** —— 故意放置误导性线索
- **时间压力** —— 每一个浪费的步骤都会增加停机时间
- **级联故障** —— 受害者看起来像罪魁祸首
**`incident-response-env` 是第一个围绕这一确切挑战构建的、符合 OpenEnv 标准的 RL 基准。**
## 🎯 它的独特之处
| Benchmark Type | What It Tests | Limitation |
|---|---|---|
| Static Q&A | 知识回忆 | 无顺序决策 |
| Code generation | 单轮输出 | 无反馈循环 |
| Tool-use benchmarks | 工具调用 | 无部分可观测性 |
| **incident-response-env** | **不确定性下的顺序诊断** | **无 —— 这是真实的 SRE 工作** |
与智能体能同时看到所有内容的基准不同，在这里智能体**只知道它查询的内容**。它必须像人类工程师那样，一步步构建对故障系统的心理模型。
## 🎮 Action Space
智能体有 7 种不同的动作类型，每种都有特定的诊断或修复目的：
```
{"action_type": "read_logs", "target": "
**Built for the OpenEnv × Scaler Hackathon 2026**
*让 AI 足够可靠，成为你的值班工程师。*
标签：Apache 2.0, Apex, DNS解析, Docker, LLM Agent, NIDS, OpenEnv, Petitpotam, SRE, 人工智能, 偏差过滤, 大模型智能体, 安全防御评估, 容器化, 库, 应急响应, 开源项目, 强化学习, 故障响应, 故障诊断, 机器学习, 根因分析, 模拟环境, 用户模式Hook绕过, 站点可靠性工程, 请求拦截, 运维自动化, 逆向工具