如何用AI Agent自主诊断K8s故障:ReAct+Prometheus+Jaeger的Troubleshooting实战教程(engenharia-de-software-com-ia-aplicada)
如何用AI Agent自主诊断K8s故障:ReAct+Prometheus+Jaeger的Troubleshooting实战教程(engenharia-de-software-com-ia-aplicada)
在开源项目 engenharia-de-software-com-ia-aplicada 的 AI-Ops 模块中,本教程带你实现 AI Agent 自主诊断 K8s 故障:用 ReAct 推理框架驱动一个 SRE Agent,联动 Prometheus 指标查询 与 Jaeger 链路追踪,自动定位故障根因并生成修复清单(Self-Healing),大幅缩短 MTTR(平均修复时间)。
💡 你不需要懂复杂的机器学习原理,跟着 5 个步骤,就能让 AI 值班 SRE 替你查日志、查指标、找瓶颈、给方案。
为什么传统K8s故障排查太慢?
生产环境的事故来临时,工程师通常要手动完成一长串动作:
| 排查动作 | 传统方式 | 痛点 |
|---|---|---|
| 查错误率 / 延迟 | 手写 PromQL 查询 Prometheus | 查询语句不熟、指标含义难记 |
| 找性能瓶颈 | 在 Jaeger 里肉眼翻几千条 Trace | 跨服务调用链太长,容易看漏 |
| 看 Pod 状态 | kubectl describe pod + 翻 Events/Logs |
CrashLoopBackOff、OOMKilled 原因各异 |
| 给修复方案 | 凭经验改 YAML 重新发布 | 深夜告警时最容易出错 |
AI Agent 的价值:把"查指标 → 查链路 → 查 Pod → 给方案"这条链路交给一个会推理的 Agent,人只在最后审批。这正是本课程 modulo06-aiops-engenharia-agentica 模块 4(Troubleshooting & Self-Healing)要解决的问题。
项目准备:安装环境并克隆代码
环境要求(来自 modulo06-aiops-engenharia-agentica/README.md):
- Python 3.10 ~ 3.13(建议避免 3.14 实验版)
- Docker 与
kubectl(用于 Kubernetes 模拟与操作) - 一个 Groq API Key(项目默认使用
llama-3.1-8b-instant模型,见 core/llm_config.py)
克隆并初始化项目:
git clone https://gitcode.com/gh_mirrors/en/engenharia-de-software-com-ia-aplicada
cd engenharia-de-software-com-ia-aplicada/modulo06-aiops-engenharia-agentica
python3 -m venv venv
source venv/bin/activate # Windows: .\venv\Scripts\activate
pip install -r requirements.txt
设置模型密钥(core/llm_config.py 通过 os.getenv("GROQ_API_KEY") 读取):
export GROQ_API_KEY="你的Groq密钥"
理解ReAct模式:思考、行动、观察的排查循环
本项目的核心教学点是 ReAct(Reasoning + Acting) 框架,出自课程幻灯片 slides/slides4.md:
- 思考(Thought):Agent 先分析当前掌握的信息,决定下一步查什么;
- 行动(Action):调用某个工具——比如查 Prometheus、查 Jaeger 或检查 Pod;
- 观察(Observation):读取工具返回结果,再进入下一轮思考。
和普通"一问一答"的 LLM 应用不同,ReAct Agent 会根据上一次工具调用的结果,动态决定下一次调用哪个工具。就像真正的值班 SRE:先看到 5XX 错误率飙升,才决定去 Trace 里找慢调用,而不是盲目把所有面板都翻一遍。
定义On-Call SRE Agent:AI值班工程师
Agent 的"人设"定义在 core/agents.py 的 get_oncall_sre 中:
- 角色:SRE On-Call (Troubleshooting Expert)
- 目标:通过定位 K8s 故障根因来降低 MTTR
- 背景设定:ReAct 专家,"先思考再行动,观察日志并关联事件"
- 能力:
allow_delegation=True,允许在需要时委派子任务
背景设定(backstory)写得好不好,直接影响 Agent 的排查风格——这是 Agent 工程里最容易被新手忽略的细节。
给Agent接入Prometheus与Jaeger:可观测性工具
工具层把可观测性平台封装成 Agent 可调用的函数,全部位于 tools/ 目录:
可观测性工具(tools/obs_tools.py)
| 工具名 | 作用 | 示例返回 |
|---|---|---|
query_prometheus_metrics |
执行 PromQL 查询 CPU、内存、延迟、错误率 | /checkout 平均延迟 850ms(超过 P99 阈值);5XX 错误率 12% |
query_jaeger_traces |
按服务名查询分布式 Trace 找瓶颈 | checkout-api 的瓶颈在 PostgreSQL 调用(Span 耗时 800ms) |
K8s 诊断工具(tools/k8s_diag.py)
| 工具名 | 作用 | 能识别的故障 |
|---|---|---|
inspect_pod_failure |
分析 Pod 日志与 Events | CrashLoopBackOff、OOMKilled、数据库连接失败 |
suggest_fix |
按故障类型给出清单修复建议 | OOMKilled → 调大 resources.limits.memory;ImagePullBackOff → 修正镜像 tag |
源码位置:tools/obs_tools.py 与 tools/k8s_diag.py。
📌 教学模块中工具返回的是结构化模拟数据,方便离线演练;生产环境只需把这些函数替换为对 Prometheus HTTP API、Jaeger API 和
kubectl的真实调用,Agent 层代码完全不用改。
实战演练:模拟K8s故障并让AI诊断根因
主脚本是 labs/modulo4_troubleshooting.py,整个演练分 3 步:
第1步:制造故障
checkout-broken.yaml 故意使用了一个不存在的镜像 tag(nginx:versao-que-nao-existe-999),Pod 会进入 ImagePullBackOff 状态:
kubectl apply -f checkout-broken.yaml # 制造故障:不存在的镜像
第2步:运行AI诊断(ReAct 核心)
python3 labs/modulo4_troubleshooting.py
SRE Agent 接到任务:"用户反馈 checkout 缓慢且报错,请用 ReAct 调查"。它会自主执行以下推理链:
Thought 1: 先看错误率与延迟 → Action: query_prometheus_metrics
Observation 1: /checkout 延迟 850ms(HIGH);5XX 错误率 12%
Thought 2: 延迟高,去 Trace 里找瓶颈服务 → Action: query_jaeger_traces(checkout-api)
Observation 2: 瓶颈在 PostgreSQL 调用,Span 耗时 800ms
Thought 3: 检查 Pod 本身状态 → Action: inspect_pod_failure(checkout-api)
Observation 3: BackOff 事件 + "Cannot connect to database at 10.0.1.5:5432"
Conclusion: 数据库连接失败(网络/配置问题)→ 建议修复清单
verbose=True 会让整个过程在终端逐步打印,非常适合新手观察 Agent 的决策过程。
第3步:应用修复并验证
kubectl apply -f checkout-k8s-fix.yaml # 应用AI生成的修复
kubectl get pods # 验证 Pod 恢复 Running
Self-Healing自愈:AI自动生成修复清单
诊断之后,modulo4_troubleshooting.py 的第二阶段由 Cloud Architect Agent 接手(labs/modulo4_troubleshooting.py),基于 SRE 的诊断结论自动生成修复后的 Deployment 清单,并通过 write_file 工具落盘。
对比 checkout-k8s-fix.yaml 可以发现 AI 遵守了任务中给出的严格规则:
- ✅ 使用
kind: Deployment(而不是孤立的 Pod) - ✅ 镜像修正为有效的
nginx:latest - ✅ 容器与探针端口统一为 80
- ✅ HTTPGet 探针
path为/(Nginx 对/healthz会返回 404) - ✅ 探针配置了
initialDelaySeconds与periodSeconds
这就是 Self-Healing(自愈) 的最小闭环:故障 → 诊断 → 生成修复 → 人工 apply → 验证恢复。真正落地时,最后一步建议加上 Human-in-the-Loop 审批(见下文进阶部分)。
进阶:从单点诊断到12个模块的AIOps生态
模块 4 只是整个 Nexus AI-Ops 课程中的一点。同目录 labs/ 下还有 11 个配套实验,覆盖完整的智能运维链路:
| 模块 | 场景 | 入口脚本 |
|---|---|---|
| 3 | K8s GitOps & Canary 发布 | modulo3_k8s_ops.py |
| 5 | 预测性 AIOps:自然语言转 PromQL,提前 4 小时预测磁盘饱和 | modulo5_aiops.py |
| 6 | ChatOps Slack 模拟(破坏性操作需人工口令) | modulo6_chatops.py |
| 10 | RAG 检索企业 Runbook 自动给出处置命令 | modulo10_remediation.py |
| 11 | Guardrails:dry-run + Human-in-the-Loop 审批 | modulo11_guardrails.py |
| 12 | 终极项目:Manager Agent 层级式编排 SRE/安全/FinOps 多 Agent | modulo12_projeto_final.py |
此外项目还提供两个统一入口:
python3 nexus_iac_copilot.py # 命令行控制中心:一键选择任意实验
streamlit run ui/app.py # 深色主题可视化 Dashboard(见 ui/app.py)
上图为项目中另一份云架构参考资料,注意其中横贯全局的 Observability(可观测性) 层——正是本文 ReAct 排查链路所依赖的 Trace/Metrics 基础。
常见问题FAQ
Q1:运行时报 ModuleNotFoundError: crewai?
确认已激活虚拟环境(source venv/bin/activate)后再运行。
Q2:Agent 不输出任何内容?
检查 GROQ_API_KEY 环境变量是否已设置,core/llm_config.py 依赖它连接模型。
Q3:没有本地 K8s 集群能跑吗?
可以。教学模块的可观测性工具返回结构化模拟结果,不依赖真实 Prometheus/Jaeger;kubectl apply 步骤可用 minikube 等本地集群模拟,或先只看 Agent 诊断输出。
Q4:如何迁移到真实环境?
把 tools/obs_tools.py 中两个函数改为请求真实 Prometheus HTTP API 与 Jaeger API,把 tools/k8s_diag.py 改为调用 kubectl logs / describe,Agent 与任务定义无需改动。
总结
本教程基于 engenharia-de-software-com-ia-aplicada 项目的 AI-Ops 模块,带你完整走通了 AI Agent 自主诊断 K8s 故障 的闭环:
- 🔍 ReAct 框架:让 Agent 按"思考 → 行动 → 观察"循环动态选择排查工具
- 📊 Prometheus + Jaeger:指标与链路追踪作为 Agent 的"眼睛"
- 🩺 K8s 诊断工具:自动识别 CrashLoopBackOff、OOMKilled 等典型故障
- 🛠️ Self-Healing:AI 生成带探针的修复清单,人工 apply 验证恢复
掌握这套"可观测性 + ReAct + 工具调用"的组合拳,你就具备了把 AI Agent 引入真实 SRE 值班流程的全部关键知识。

