Aman855180/incident-response-agent-final

# 自主 IT 事件响应 — Agentic 工作流 POC 一个基于 LangGraph 的多智能体系统，它可以接收遥测警报，诊断可能的 根本原因，选择并执行修复措施，验证结果，并生成 事件报告 —— 并且将受策略约束的决策制定和故障恢复内置于 图本身。 作为 AI 研究员居家作业评估第 2 部分而构建。第 1 部分（关于 基于轨迹的评估以及 GPT-4.1 与 Qwen3-32B-Instruct 的研究报告）位于 `report/` 中，并且其描述的 评估 pipeline 已在 `evaluation/` 中实现并可运行。第 3 部分 （产品策略演示）位于 `presentation/` 中。 ## 项目概述 **问题：** 对于大量常见的、易于理解的故障模式（资源耗尽、依赖降级、瞬态 应用错误），手动进行事件分诊既缓慢又重复。此 POC 演示了一个 agentic 工作流，该工作流可自动执行该类问题的分诊和 低风险修复，同时对于任何 不明确的、高严重性的或超出其策略范围的情况，明确地将其升级给人工处理。 **非目标：** 这并不是主张每个事件都应该完全自动化。Decision Agent 的策略被刻意设定为保守的（在置信度低或严重性为关键级别时进行升级） — 请参阅 `prompts.py::DECISION_AGENT_SYSTEM_PROMPT`。 ## 架构 

Mermaid 源码（在 GitHub 上实时渲染）

``` flowchart TD Alert[Telemetry Alert] --> Monitor[Monitor Agent
triage + severity] Monitor --> Diagnosis[Diagnosis Agent
query_logs, get_metrics,
check_dependency_health] Diagnosis --> Decision[Decision Agent
policy-constrained
action selection] Decision --> Execution[Execution Agent
calls remediation tool,
retries once on failure] Execution --> Verification[Verification Agent
verify_slo] Verification -->|resolved or escalated| Report[Report Agent
synthesizes incident report] Verification -->|not resolved,
retry budget remains| Decision Report --> Output[Incident Report] ```

单个警报的序列（理想路径）： ``` sequenceDiagram participant A as Alert participant M as Monitor participant D as Diagnosis participant DE as Decision participant E as Execution participant V as Verification participant R as Report A->>M: TelemetryAlert M->>D: genuine incident, severity D->>D: query_logs / get_metrics / check_dependency_health D->>DE: diagnosis {hypothesis, confidence} DE->>E: chosen_action {action, arguments} E->>E: execute tool (retry once on failure) E->>V: execution_result V->>V: verify_slo V->>R: resolved R->>A: final incident report ``` ### 模块映射 | 文件 | 职责 | |---|---| | `state.py` | 类型化图状态（`IncidentState`），`ToolCall`/`AgentDecision` 轨迹记录 | | `tools.py` | 模拟工具 API（日志、指标、依赖健康状况、重启/扩缩/回滚/寻呼、SLO 检查），带有确定性故障注入 | | `prompts.py` | 所有 agent 提示模板，与控制流保持分离 | | `llm_client.py` | 可插拔的 LLM 后端 —— 默认情况下是确定性 mock；如果设置了相关密钥，则使用真实的 Anthropic、GPT-4.1 (OpenAI) 或 Qwen3-32B (OpenAI 兼容) 客户端 | | `agents.py` | 六个图节点（Monitor、Diagnosis、Decision、Execution、Verification、Report） | | `graph.py` | LangGraph `StateGraph` 连线，包括验证 -> 重试或升级的条件边 | | `app.py` | CLI 入口点 —— 通过图运行示例警报 | | `evaluation/trajectory_eval.py` | 基于规则的轨迹评分器，实现了第 1 部分的方法论 | | `evaluation/test_core.py` | 针对评分器和工具逻辑的单元测试 | | `evaluation/run_model_comparison.py` | GPT-4.1 与 Qwen3-32B 的正面交锋测试工具（延迟、JSON 有效性、工具选择、恢复）—— 已实现，需要凭据才能执行 | | `report/research_report.md` | 第 1 部分交付成果 | | `report/assets/` | 渲染后的架构图和真实的终端运行截图 | | `presentation/` | 第 3 部分交付成果 | | `decision_log.md` | AI 工具使用情况和手动架构决策 | ## 安装 ``` python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` 运行演示不需要 API 密钥 —— 有关 mock 模式 LLM 后端 能够做什么和不能做什么，请参阅[局限性](#limitations)。 要使用真实模型代替确定性 mock： ``` export ANTHROPIC_API_KEY=sk-... ``` `llm_client.get_llm_client()` 会自动获取密钥，并通过 `AnthropicLLMClient` 进行路由，而不是使用 `MockLLMClient`；不需要更改其他代码。 ## 执行 ``` # 运行所有 sample alerts python app.py # 运行单个 scenario python app.py --alert checkout # dependency-degradation -> escalate python app.py --alert payments # OOM -> scale_service python app.py --alert unknown # generic error -> restart_service (with injected failure + retry) python app.py --alert transient # no evidence -> low-confidence escalate # 为 evaluation dump 完整 trajectories python app.py --json /tmp/trajectories.json python evaluation/trajectory_eval.py /tmp/trajectories.json ``` ### 示例运行 `python app.py --alert unknown` 的真实捕获输出 —— 选择此示例是因为它是 会触发注入的工具故障以及重试后成功恢复路径的场景：  *（基于[局限性](#limitations)/`decision_log.md` 中描述的本地 API shim 捕获 —— 输出和控制流是真实的，但底层的图执行引擎被替换了。）* ### GPT-4.1 与 Qwen3-32B-Instruct 对比 `evaluation/run_model_comparison.py` 是一个完整的、随时可运行的测试工具，它通过相同的图在两个模型上运行相同的 4 个 场景，并并行报告延迟、JSON 有效性、工具选择 正确性以及故障恢复情况。由于此沙箱中缺少 API 凭据，在此提交中并未针对实时模型执行它（请参阅 `decision_log.md` 和 `report/research_report.md` §0）—— 相反，其控制流已针对 mock 客户端进行了验证。 针对真实环境运行它： ``` export OPENAI_API_KEY=sk-... export QWEN_API_KEY=... export QWEN_BASE_URL=https://api./v1 # any OpenAI-compatible Qwen3 host python -m evaluation.run_model_comparison --n 3 ``` 对于大规模的生产追踪/评估，[LangSmith](https://www.langchain.com/langsmith) 是 此类轨迹捕获的行业标准工具，并且是超越此仓库手动编写的 `evaluation/` 脚本之后的自然下一步 —— 请参阅研究报告 §2.4。 运行单元测试： ``` pytest evaluation/test_core.py -v ``` ### 可选：本地 UI `streamlit_app.py` 是建立在相同的 `graph.py`/`app.py` 代码路径之上的轻量级 UI —— 选择一个 场景，运行它，以交互方式查看报告、轨迹和评估分数，而不是阅读 CLI 输出。 ``` pip install -r requirements-ui.txt streamlit run streamlit_app.py ``` 此操作**仅在本地运行** —— 此仓库中的任何内容都未进行部署或托管，因为 此环境没有可供部署的网络访问权限。它也是此提交中唯一一个 进行了语法检查但未进行端到端执行测试的文件（Streamlit UI 是一个轻量级前端，覆盖在 CLI 使用的相同图和评估 pipeline 之上。它已在本地进行了测试，允许用户交互式地执行场景、查看事件报告、轨迹和评估结果 —— 请参阅 `decision_log.md`）；它导入了与此仓库中所有其他测试所调用的相同的 `build_graph`/`score_trajectory` 函数，因此 风险仅限于 Streamlit 特定的渲染调用，而非底层逻辑。 ## 仓库结构 ``` incident-response-agent/ ├── README.md ├── requirements.txt ├── app.py ├── graph.py ├── agents.py ├── state.py ├── tools.py ├── prompts.py ├── llm_client.py ├── decision_log.md ├── evaluation/ │ ├── trajectory_eval.py │ ├── test_core.py │ └── run_model_comparison.py ├── report/ ├── research_report.md ├── research_report.pdf └── assets/ │ ├── architecture.png │ └── terminal_run.png └── presentation/ └── product_strategy.pptx ``` ## 评估方法论 完整方法论请参阅 `report/research_report.md` §2。简而言之：每次运行都会生成一个 结构化的轨迹（`IncidentState` 累积的 `tool_calls` 和 `decisions`）， `evaluation/trajectory_eval.py` 会根据基于规则的指标对其进行评分 —— 规划质量、工具 选择准确性、故障恢复、幻觉工具率、状态一致性、任务 成功（通过 `verify_slo` 独立验证，而非 agent 自身的声明）以及延迟。 该评分器在 `evaluation/test_core.py` 中针对具有已知良好和已知不良 属性的合成轨迹进行了单元测试。 ## 局限性 - **默认使用 Mock 模式的 LLM。** 如果没有 API 密钥，所有的“推理”都是一个确定性的 基于规则的 stub（`MockLLMClient`），而不是实际的语言模型。这是一个经过深思熟虑的 选择，以便该仓库能够以零成本和零设置阻力运行和演示， 但这意味着该演示并未展示真实的 LLM 推理质量 —— 仅展示了 图的编排、状态管理以及围绕它的故障恢复控制流。切换到 `AnthropicLLMClient`（或为其他提供商实现等效功能）将使用真实的 模型推理来执行相同的图。 - **已通过 LangGraph 0.2.x 测试。** 该项目已通过从 requirements.txt 安装依赖项、运行示例场景、生成轨迹、执行评估 pipeline 以及通过包含的单元测试进行了验证。对于未来的 LangGraph 版本，可能需要进行微小的兼容性调整。 - **`memory` 字段仅在单次运行内有效。** `IncidentState.memory` 会在单个事件的 轨迹内累积备注，但不会在不同的独立运行/事件之间持久化 —— 请参阅 未来工作。 - **小型的、固定的工具集。** 在这种规模下（8 个工具），不需要工具路由（研究报告的 §4.8），但如果使用更大的目录则需要。 - **没有细粒度的成本模型。** 跟踪了延迟；但未跟踪每次运行的 token/美元成本， 因为 mock 模式不会产生 LLM 成本。 ## 未来工作 - 使用以服务名称为键的持久化向量存储来支持 `IncidentState.memory`，以便 Diagnosis Agent 可以检索类似的过去事件（请参阅研究报告 §4.4、§4.7）。 - 在高影响范围操作（`rollback_deployment`）之前添加反思/自我纠正阶段， 而不是直接执行 Decision Agent 的首选操作 （研究报告 §4.3）。 - 运行 `evaluation/run_model_comparison.py`（已构建 —— 请参阅[执行](#execution)）来对抗 真实的 GPT-4.1 和 Qwen3-32B-Instruct 凭据，然后将其扩展到更大的、 对抗性设计的警报集（模糊的诊断、超出策略的诱惑场景），以便 用实际的评分卡替换研究报告中经过推理但未测量的比较。 - 添加 LLM-judge 流程（采样，而非穷举）以进行推理质量评分，以补充 现有的基于规则的指标。 - 将工具调用连接到相同的 `tools.py` 接口背后的真实后端（Prometheus/Datadog、Kubernetes API、PagerDuty）—— 编写 mock 函数时使用了匹配的签名，以使其 能够直接替换。 ## 决策日志 请参阅 [`decision_log.md`](decision_log.md)。

标签：AIOps, AI智能体, IT运维, Kubernetes, LangGraph, Petitpotam, Socks5代理, 安全规则引擎, 模块化设计, 自动化修复, 逆向工具