多智能体 V2 全功能详解
从告警分析到全栈智能体平台
Deep Agents 架构 · 八大专家协作 · 四种入口 · Backstage 集成
本文是一篇全景式的技术详解，完整覆盖多智能体 V2 的 16+ 个功能模块。如果你只把它当作"告警分析工具"，那你会错过它 90% 的价值。文章较长，建议先收藏，按需查阅。每个模块都包含：能力描述、适用场景、关键设计点，并配以 SVG 架构图。
🛠 SRE 工程师、平台工程师、AI Infra 关注者 都能从中找到价值。
💡 读完你将了解：如何用一套系统，把告警根因分析、工单管理、CI/CD 排障、集群诊断、容量预测全部自动化。
多智能体 V2：一个会"查、会想、会写"的 SRE 团队成员
企业微信一条告警打破了平静：
📱 "【告警】某服务 5xx 错误率激增，已持续 3 分钟。"
如果是 V1 时代，你需要：
🔍 打开 Grafana 看指标 → 切到日志平台翻报错 → 去链路系统追 trace → 登录集群查 Pod → 翻 Jira 看有没有相关工单 → 去代码仓库查最近改动 → 写一份分析报告。
⏱ 这一圈下来，30 分钟起步，而且全靠经验。
V2 时代，你只需把告警丢给多智能体：
🤖 它会自动拉日志、追链路、查集群状态、定位代码行、搜索历史工单、匹配根因模式，最后给你一份结构化的 RCA 报告，并建议是否需要创建工单。
⏱ 全程 1-3 分钟，结果可回放、可审计。
本文要讲的，就是这个 V2 系统的每一个零件。
🎯 一、系统概述：从多智能体到深度智能体
V2 不只是"多了几个 Agent"，而是把协调方式从"路由转发"升级为"深度推理"
1.1 V1 到 V2 的进化
本系统的 V1 采用经典的 Supervisor 多智能体模式：一个 Supervisor 负责接收用户请求，根据意图把任务"路由"给对应的专家 Agent（TraceAgent、MetricsAgent 等），再把结果汇总返回。
这个模式在"单一领域问题"上表现良好，但面临三类痛点：
- 🧩 跨领域联动弱：一次根因分析往往需要"链路 + 指标 + 日志 + 集群事件"四路并查，Supervisor 很难在一次调度里把多个专家串联起来做深度推理。
- 🔁 多轮工具调用不可控：复杂任务需要反复调用工具、对比结果、修正假设，V1 的单轮路由无法支撑这种"边查边想"的循环。
- 📝 缺乏持久化中间状态：V1 的中间结论散落在各 Agent 内部，无法被后续步骤稳定复用，也无法跨会话回放。
V2 引入 Deep Agents 框架，把协调中枢从"转发路由器"升级为"会写笔记、会做计划的深度推理中枢"。核心变化有三：
- 计划与笔记：Deep Agent 在执行过程中会把假设、中间结论、待办事项写入"虚拟文件系统"，后续步骤可以读取，形成可累积的推理链。
- 工具循环：协调中枢可以在一轮对话内多次调用专家工具，根据返回结果调整下一步，直到收集到足够证据再下结论。
- 技能注入：通过 SkillsMiddleware 按需加载领域知识，让协调中枢在"不懂"某个场景时能临时"学会"。
1.2 八大专家协作架构
V2 的能力由八个专家 Agent 提供，每个专家都有独立的工具集、系统提示和技能挂载。协调中枢（Deep Agent）根据问题类型决定调用哪些专家、以什么顺序调用。
1.3 关键设计点
- 专家即工具：每个专家 Agent 被包装成一个 StructuredTool，协调中枢像调用普通函数一样调用专家，专家内部再调用各自的工具集。这种"工具嵌套工具"的设计让架构可组合、可扩展。
- 结果截断保护：专家返回结果最长 8000 字符，超过则按换行/句号智能截断，避免协调中枢上下文爆炸。
- 回调传播：通过 callback_context 在专家和工具之间传播 Langfuse 回调，实现全链路追踪。
- 技能按需挂载：协调中枢通过 SkillsMiddleware 在运行时加载技能目录下的知识文件，不占用常驻上下文。
🚨 二、告警分析（RCA 流水线）
V2 把告警分析拆成"两批流水线"，先查事实再追代码，兼顾速度与深度
2.1 为什么需要"两批"流水线
告警根因分析（RCA）的核心矛盾是：速度与深度的取舍。只查日志很快，但可能找不到根因；同时追日志、链路、代码、工单，虽然全面，但耗时长且容易让模型在大量信息中"走神"。
V2 的解法是把 RCA 拆成两批，按"证据充分度"递进：
2.2 能力描述
Batch 1（日志先行）聚焦"发生了什么"：
- 按服务名 + 时间窗口查询 ERROR 日志，对相似错误做聚合统计，避免被重复日志淹没。
- 从日志中提取 traceId，若存在则追查完整调用链，定位异常发生在哪个服务、哪个接口。
- 识别常见异常类型（连接超时、空指针、连接拒绝、数据库异常等），并提取业务代码堆栈，过滤掉框架噪声。
Batch 2（代码追溯）聚焦"为什么发生"：
- 用 Batch 1 的异常类名和堆栈信息，在代码仓库中精确搜索可疑代码段。
- 拉取该服务最近的 Merge Request，判断问题是否由近期代码变更引入。
- 并行调用 KubernetesAgent 查 Pod 事件（CrashLoopBackOff/OOMKilled）、MetricsAgent 确认指标异常是否与日志时间吻合。
- 综合所有证据，给出根因结论、证据链和处置建议。
2.3 TraceAgent 的调用决策规则
TraceAgent 在流水线中扮演关键角色，但它并非每次都调用——V2 为它设计了一套确定性决策规则，而非让 LLM 自行判断：
- 有 traceId：直接调用 search_logs_by_trace，追全链路。
- 无 traceId 但有 URL：调用 search_logs_by_keyword，用接口路径作为关键词检索。
- 只有服务名：调用 search_logs_by_service，按时间窗口批量拉取后人工/规则提取 traceId。
- 纯关键词线索（如订单号、手机号片段）：调用 search_logs_by_keyword 精确命中。
这套规则确保 TraceAgent 不会"瞎调"，也避免在缺乏 traceId 时空转。
2.4 交付优先级
两批流水线的输出遵循"先交付、后深化"的原则：
| 优先级 | 交付物 | 触发条件 |
|---|---|---|
| P0（即时） | 告警概要 + 错误聚合 + traceId | Batch 1 完成 |
| P1（随后） | 完整调用链 + 业务堆栈定位 | traceId 追查成功 |
| P2（最终） | 根因结论 + 代码定位 + 处置建议 | Batch 2 完成 |
这种分批交付意味着：即使用户在 Batch 2 进行中就急于查看，也能先拿到 P0/P1 的中间结果，不会干等。
📋 三、Jira / Confluence 知识搜索与工单管理
让 Agent 既能"查历史"，也能"开工单"——15 个工具 + 1 个事件复合工具
3.1 Jira 九大工具
AtlassianAgent 通过两种方式与 Atlassian 平台交互：Jira 走 ACLI（Atlassian CLI）子进程，Confluence 走 REST API。共提供 9 个 Jira 工具：
| 工具 | 功能 | 适用场景 |
|---|---|---|
| jira_get_issue | 查看单个工单详情 | 用户给出工单号时快速取详情 |
| jira_search_issues | JQL 搜索工单 | 按服务/状态/时间批量查 |
| jira_create_issue | 创建工单 | 根因分析后开修复单 |
| jira_update_issue | 更新工单字段 | 补充根因/影响范围 |
| jira_comment_issue | 添加评论 | 把分析报告追加到工单 |
| jira_transition_issue | 状态流转 | 把工单从"待处理"流转到"进行中" |
| jira_link_issues | 关联工单 | 把告警工单和根因工单关联 |
| jira_list_projects | 列出所有项目 | 确认工单该建到哪个项目 |
| jira_list_sprints | 列出 Sprint | 把工单归入当前迭代 |
3.2 Confluence 六大工具
| 工具 | 功能 | 适用场景 |
|---|---|---|
| confluence_search | CQL 全文搜索 | 搜"某服务部署文档" |
| confluence_get_page | 按 ID 获取页面 | 已知页面 ID 时直接取正文 |
| confluence_get_page_by_title | 按标题查找页面 | 用户说"那个排障手册" |
| confluence_list_spaces | 列出所有空间 | 确认知识归属团队 |
| confluence_get_space_content | 浏览空间内容 | 逛某个团队的知识库 |
| confluence_create_page | 创建页面 | 把 RCA 报告沉淀为文档 |
3.3 事件复合工具：一键创建事件工单
除了 15 个原子工具，V2 还封装了一个事件复合工具 jira_create_incident，把"建工单 + 加标签 + 写结构化评论"三步合一：
3.4 只读模式与写入模式
出于安全考虑，AtlassianAgent 支持只读模式和写入模式两种运行态：
- 只读模式（默认）：仅启用查询/搜索/浏览类工具（jira_get_issue、jira_search_issues、confluence_search 等），所有创建/更新/流转工具被禁用。适合日常排障、查历史工单。
- 写入模式：需显式开启，解锁 jira_create_issue、jira_update_issue、jira_transition_issue、jira_create_incident、confluence_create_page 等。适合"分析后自动建单"的闭环场景。
这种分级设计让 Agent 在"只查不写"的窗口期内即使误调用也不会产生副作用。
3.5 工具调用上限保护
与 GitLabAgent 类似，AtlassianAgent 也设置了单次 25 次工具调用上限（_ATLASSIAN_TOOL_RUN_LIMIT = 25）。这个数字的考量：
- 一次完整的事件工单创建（搜项目→搜工单→创建→加标签→写评论→关联）大约需要 6-10 次调用。
- 批量搜索场景（如按服务查所有相关工单）可能需要 5-8 次调用。
- 25 次既覆盖了"搜索 + 创建 + 关联"的复合场景，又防止 Agent 在反复搜索中失控。
同时 AtlassianAgent 的递归上限也要求 ≥ 25，启动时校验，避免配置矛盾。
3.6 告警解析 → 标签推荐 → 工单格式化
当告警触发自动建单时，V2 会做三件事：
- 告警解析：从告警文本提取服务名、接口、错误率、时间窗口。
- 标签推荐：根据服务名和严重度，自动推荐 incident、服务名、环境等标签，便于后续按标签过滤。
- 工单格式化：把 RCA 报告结构化为标题、摘要、影响范围、根因、处置建议、traceId 等字段，写入工单评论，让接手人一目了然。
🔧 四、GitLab CI/CD 排障与代码分析
从"发版失败"到"谁改坏了代码"——GitLabAgent 用 28 个自制工具 + 186 个官方 glob 工具覆盖研发全链路
4.1 工具全景
GitLabAgent 通过 HTTP 直连 GitLab API（无需 sidecar），提供 28 个自制工具 + 186 个官方 glob 工具（通过 glab mcp serve 动态加载），覆盖六大类操作：
• 自制工具（28 个）：基于 GitLab REST API 封装的
gitlab_* LangChain 工具，针对 SRE 排障场景深度定制——MR 分析、CI 失败启发式诊断、发版回溯、贡献者统计、代码搜索等• Glob 官方工具（~186 个）：通过
glab mcp serve 动态加载的 GitLab CLI 原生 MCP 工具，覆盖 API 全部能力域（MR/CI/仓库/Issue/Runner/Release/集群等 30 个域）；只读 PAT 模式下约 77 个可暴露，写入类约 109 个按需开启
| 类别 | 工具 | 能力 |
|---|---|---|
| 项目与代码搜索 | gitlab_search_projects | 按名称模糊搜索项目 |
| gitlab_get_project | 获取项目详情 | |
| gitlab_list_namespaces | 列出命名空间 | |
| gitlab_code_search | 代码内容搜索（定位可疑代码段） | |
| gitlab_lookup_user / gitlab_list_user_projects | 查用户与其项目 | |
| Merge Request 管理 | gitlab_list_merge_requests | 列出 MR（按状态/时间过滤） |
| gitlab_get_merge_request | MR 详情 | |
| gitlab_get_merge_request_diffs | MR diff 对比 | |
| gitlab_merge_request_change_insight | 参与者分析与变更洞察 | |
| 仓库文件操作 | gitlab_get_file_contents | 读取文件内容 |
| gitlab_list_commits / gitlab_get_commit | 提交历史 | |
| gitlab_author_code_stats | 作者代码统计 | |
| gitlab_contributor_ranking（含 combined/snapshot 变体） | 贡献者排名 | |
| Issue 与 Pipeline | gitlab_get_issue / gitlab_search_issues | Issue 查询 |
| gitlab_get_pipeline / gitlab_list_pipelines | Pipeline 查询 | |
| gitlab_list_pipeline_jobs / gitlab_list_project_jobs | Job 列表 | |
| gitlab_get_job / gitlab_get_job_trace | Job 详情与日志 | |
| gitlab_analyze_failed_job | 失败 Job 启发式分析 | |
| 分支与发版 | gitlab_ops_release_fail_diagnosis | 发版失败一键诊断 |
| gitlab_sweep_author_code | 作者代码扫描清理 |
4.2 CI 启发式分析：自动识别失败原因
CI 失败日志动辄上万行，让人眼花。V2 内置一套启发式分析引擎，对 CI 日志做智能打标和关键行提取：
识别的失败类别（标签）：
npm/yarn_pnpm：前端依赖/构建错误jvm_build：Maven/Gradle 构建失败test_runner：pytest/JUnit/Jest 测试失败static_analysis：Checkstyle/SpotBugs/PMD 静态检查违规container：Docker 镜像构建/拉取失败k8s_deploy：Helm/Kubectl 部署失败permission：权限拒绝（如镜像仓库 403）resource：OOM/Killed/资源不足network：连接拒绝/超时/TLS 握手失败
引擎会用正则匹配 error/exception/failed/fatal 等关键词，并优先提取 Java 堆栈中的 文件名:行号，帮助快速跳转到出错代码。
4.3 发版失败一键诊断
gitlab_ops_release_fail_diagnosis 是一个"大杀器"级工具：用户只需提供发版通知（包含项目、分支、时间），它会自动：
- 解析发版通知，提取项目、分支、阻塞阶段。
- 定位对应的 Pipeline 和失败的 Job。
- 拉取 Job 日志，跑启发式分析，输出失败类别和关键行。
- 若失败涉及代码，搜索最近的 Merge Request，判断是否由变更引入。
- 综合输出：失败原因 + 关键日志行 + 关联 MR + 处置建议。
4.4 工具调用上限保护
GitLabAgent 设置了 单次 36 次工具调用上限（_GITLAB_TOOL_RUN_LIMIT = 36）。这个数字的由来：
- 一次完整的发版诊断大约需要 10-15 次调用（查项目→查 pipeline→查 job→拉日志→查 MR→查 diff）。
- 贡献者排名类操作可能需要遍历多个仓库，每次 5-8 次调用。
- 36 次既覆盖了复杂场景，又防止 Agent 在"无限翻页"或"循环搜索"中失控。
配置中还要求 thread 级上限 ≥ 36，启动时会校验，避免配置矛盾。
🕸️ 五、业务依赖与架构梳理
告警来了，先搞清楚"它是谁、它依赖谁、谁依赖它"
5.1 能力描述
一次根因分析能否准确，很大程度上取决于你是否清楚"故障服务在架构中的位置"。V2 提供一套业务依赖梳理能力：
- 服务依赖盘点：分析服务代码中的 Feign/RestTemplate/WebClient 配置，自动识别它的下游依赖。
- 服务拓扑映射：基于依赖盘点结果，构建服务间调用拓扑图，可视化"谁调谁"。
- 服务状态检查：对拓扑中的每个服务，快速检查其健康状态（Pod 是否就绪、接口是否可达）。
- 架构知识库：维护团队归属、namespace 映射、服务负责人等元信息，让 Agent 知道"这个服务归谁管"。
- 告警归因：把告警标题精确映射到服务名——告警里写的可能是缩写或别名，需要归一到标准服务名才能继续查。
5.2 适用场景
- 告警归因：告警标题"gateway 超时" → 归一为标准服务名 → 才能查日志和链路。
- 影响面评估：服务 A 故障 → 盘点谁依赖 A → 判断影响哪些上层业务。
- 排障导航：拿到告警后，先看拓扑定位故障服务在调用链中的位置，再决定查上游还是下游。
- 新人 onboarding：新成员问"某服务是干什么的"，Agent 可以基于架构知识库回答。
5.3 关键设计点
- 归因优先：任何告警分析的第一步都是归因，映射失败则后续查询全部落空，所以归因表需要持续维护。
- 静态分析为主：依赖盘点基于代码配置静态分析，不依赖运行时流量，避免在故障期间加重系统负担。
- 知识库可人工补录：自动盘点可能漏掉动态调用，知识库支持人工补录"隐藏依赖"。
☸️ 六、Kubernetes 集群诊断
从"Pod 挂了"到"为什么挂"——KubernetesAgent + 原生 kubectl 双层诊断
6.1 集群清单：一眼看全
KubernetesAgent 提供集群资源的完整清单查询，覆盖五个维度：
| 维度 | 查询能力 | 典型用途 |
|---|---|---|
| namespace | 列出所有命名空间 | 确认服务归属 |
| workload | Deployment/StatefulSet/DaemonSet | 查副本数、镜像版本 |
| pod | Pod 列表与详情 | 查重启次数、状态 |
| node | 节点资源概况 | 查节点是否压力 |
| service | Service/Endpoint | 查流量是否就绪 |
6.2 事件与健康分析
集群事件是诊断的金矿。KubernetesAgent 自动解析 K8s 事件，识别常见故障模式：
- CrashLoopBackOff：容器反复崩溃重启，通常是启动失败（配置错误/依赖缺失）。
- OOMKilled：内存超 limit 被杀，需要调大 limit 或排查内存泄漏。
- 探针失败：liveness/readiness 失败，可能是启动慢或依赖不可达。
- 调度问题：Pending 状态，可能是资源不足或节点亲和性/污点导致无法调度。
- 镜像拉取失败：ImagePullBackOff，镜像名错误或仓库权限问题。
6.3 资源诊断
除了事件，KubernetesAgent 还做资源层面的深度诊断：
- CPU/内存/磁盘压力：查节点资源使用率，判断是否过载。
- Top 消费者：列出资源占用 Top N 的 Pod，快速定位"谁在抢资源"。
- request/limit 不匹配：检测 request 远低于 limit 的配置，这类配置容易在突发流量下被 throttling。
6.4 安全检查
V2 还内置了安全巡检能力，检测高危配置：
- 特权 Pod：
privileged: true的容器，拥有宿主机级权限。 - hostPath 挂载：直接挂载宿主机目录，可能突破隔离。
- 危险能力：如
SYS_ADMIN、NET_ADMIN等 capability。
6.5 RCA 辅助与原生 kubectl 直连
KubernetesAgent 的真正价值在于联合分析：把 K8s 事件、Prometheus 指标、应用日志三者交叉印证。例如：
Pod 在 14:03 被 OOMKilled → MetricsAgent 确认该 Pod 内存曲线在 14:02 飙升 → LogAgent 查到 14:01 开始有"大查询"日志 → 三者吻合，根因是"大查询导致内存飙升触发 OOM"。
此外，V2 还提供原生 kubectl 工具（pods_list、pods_get、events_list、resources_get、resources_list、pods_log、pods_top），这些工具通过 subprocess 直接调用 kubectl CLI（不走 MCP），让 Agent 在需要时获得更底层的集群访问能力，灵活性更高。
🗄️ 七、数据库与性能分析
MySqlAgent + 慢查询关联 + HTTP 延迟分析
7.1 MySQL 表结构与索引分析
MySqlAgent 能连接 MySQL，提供：
- 表结构查看：列出指定库表的字段、类型、注释。
- 索引分析：查看表的索引情况，判断查询是否走索引。
- 执行计划：对可疑 SQL 跑 EXPLAIN，看扫描行数、是否全表扫描。
7.2 慢查询关联定位
数据库慢查询往往和业务延迟强相关。V2 的做法是把链路中的 SQL 提取出来，与慢查询日志关联：
7.3 HTTP 延迟分析
接口慢不一定是 DB 慢。V2 的 HTTP 延迟分析把一次请求的耗时分段分解：网关耗时、服务处理耗时、DB 查询耗时、下游调用耗时。这样能精确定位"慢在哪一段"，而不是笼统地说"接口慢"。
7.4 链路中 SQL 提取
TraceAgent 在追链路时，会把每个 span 中的 SQL 语句提取出来，传递给 MySqlAgent 做进一步分析。这种"链路 → SQL → EXPLAIN"的串联，是数据库性能问题的标准排查路径。
📊 八、OpenSearch 容量预测
不只是查日志——OpenSearchAgent 还能预测"磁盘什么时候满"
8.1 索引健康度分析
OpenSearchAgent 分析索引层面的健康度：
- 索引大小与文档数：每个索引的存储占用和文档量。
- ISM 策略：索引是否配置了生命周期管理，retention 是多少。
- 日期后缀识别：自动识别按天滚动的索引（如
某索引-YYYYMMDD），只对这类索引做容量预测。
8.2 Top 统计
从 span 数据中统计 Top N：
- Top 服务：产生 span 最多的服务。
- Top 接口：调用最频繁的接口。
- Top 属性：出现最多的 span 属性（如 error.type）。
8.3 存储概况与历史趋势
OpenSearchAgent 会汇总集群的存储概况，并基于历史数据绘制增长趋势：
8.4 容量预测：索引族级别 + 集群级别
V2 的容量预测分两级：
- 索引族级别：对每个索引族（如 otel-span、app-log），基于历史每日增量预测未来增长，估算何时达到 retention 上限或磁盘警戒线。
- 集群级别：汇总所有索引族，预测集群整体磁盘使用率，给出"预计 X 天后达到 80%"的结论。
这套预测依赖"按天滚动索引 + retention"前提，因此只纳入带日期后缀的索引，排除系统索引和别名索引。
🔄 九、发版前后对比
发版后出问题？先对比"发版前 30 分钟"和"发版后 30 分钟"
9.1 能力描述
compare_release_before_after 工具接受一个人工指定的发布时刻 T，自动对比 T 前后各 30 分钟（固定窗口）的关键指标：
| 数据源 | 对比维度 |
|---|---|
| OpenSearch | ERROR/WARN 条数、错误率、发版后新增的 ERROR 样例 |
| Prometheus（内置 PromQL） | Pod CPU/内存、OTEL 接口延迟 P99、请求量、5xx 速率 |
| CloudWatch（可选） | RDS 实例 CPU/内存/连接数、ElastiCache 集群指标 |
9.2 关键设计点
- 固定 30 分钟窗口：不通过环境变量配置，避免随意调整导致对比口径不一致。
- Pod 名正则容错：Pod 名一般是
{service}-{rs-hash}-{suffix}，正则只转义真正的元字符，避免连字符被过度转义导致匹配失败。 - exported_job 双写兼容：OTEL 的 exported_job 可能是"服务名"或"服务名-prod"，正则同时匹配两种写法。
- Prometheus 闸门：一旦 Prometheus 超时/连接失败，后续内置 PromQL 自动跳过，避免 N×条数×2 窗口的重复失败调用。
🎓 十、技能系统：30 个技能目录，按需加载
给 Agent 一本"随时翻阅的操作手册"
10.1 什么是技能
技能（Skill）是一段 Markdown 格式的领域知识，告诉 Agent"在什么场景下、该用什么工具、按什么步骤做"。与系统提示不同，技能不是常驻的，而是由 SkillsMiddleware 在运行时按需加载，避免上下文膨胀。
10.2 30 个技能目录分类
| 类别 | 技能目录 |
|---|---|
| 告警与排障 | alarm-to-code-workflow、alarm-types、alarm-workflow、error-fragment-investigation、troubleshooting-patterns、investigation-toolkit |
| 架构与依赖 | service-dependencies、service-topology、service-status-check、company-context、account-system |
| Kubernetes | k8s-pod-resources、pod-health-analysis、hosts-resources |
| 数据库与性能 | slow-query-analysis、http-latency-analysis |
| CI/CD | ci-cd-troubleshooting、deployment-rollout、merge-request-triage |
| 工单与知识 | jira-triage、confluence-knowledge-base、incident-workflow、atlassian-tool-reference |
| GitLab | glab-hybrid-tools、glab-mcp-tool-catalog、glab-mcp-tool-selection、author-contribution-workflows |
| 容量与成本 | capacity-forecasting、aws-cost-calculator |
| 工具参考 | tool-usage-reference |
10.3 按需加载机制
技能加载有两种结构：
- 新结构：
skills/skill-name/SKILL.md，每个技能一个目录，便于附带示例文件。 - 旧结构：
skills/*.md，扁平文件，兼容历史。
SkillsMiddleware 扫描 skills/ 目录，把所有 SKILL.md 加载为虚拟文件，Deep Agent 在推理时按需读取。技能内容不会全部塞进系统提示，而是作为"可检索的知识库"存在。
10.4 各 Agent 的技能挂载
不同专家 Agent 挂载不同的技能子集，避免"日志专家被 Kubernetes 技能干扰"：
- TraceAgent / LogAgent：alarm-types、error-fragment-investigation、troubleshooting-patterns
- KubernetesAgent：k8s-pod-resources、pod-health-analysis、hosts-resources
- MySqlAgent：slow-query-analysis、http-latency-analysis
- GitLabAgent：ci-cd-troubleshooting、merge-request-triage、author-contribution-workflows
- AtlassianAgent：jira-triage、confluence-knowledge-base、incident-workflow
⚙️ 十一、服务端工程实践
生产级 Agent 的"看不见的功夫"
11.1 SSE 心跳防断连
Agent 推理可能耗时数十秒，期间如果没有数据流过，反向代理（如 Nginx）会因超时断开连接。V2 的解法是SSE 心跳：
- 每 30 秒（
HEARTBEAT_INTERVAL）若无事件产生，发送: heartbeat\n\n注释帧。 - SSE 注释帧被所有客户端忽略，不影响业务数据。
- 30 秒远低于代理的 2-3 分钟超时，确保连接不被掐断。
- 心跳与真实事件通过
asyncio.wait竞争，一旦有真实事件立即发送，不等心跳。
11.2 并发 Run 取消
用户在流式输出过程中刷新页面或重新提问，会产生新的 Run。如果不取消旧 Run，会导致：
- 资源浪费：旧 Run 继续消耗 LLM tokens 和工具调用。
- 状态污染：两个 Run 同时写同一 thread 的 checkpointer。
V2 维护 _active_runs 字典（thread_id → run 信息），新 Run 启动时检查同 thread 是否有活跃 Run，有则通过 cancel_event.set() 取消旧 Run，并清理 graph/checkpointer 资源。
11.3 消息后处理管道
模型输出有时会"啰嗦"——在给出完整报告后又追加一句"还有什么需要帮助的吗？"这类低价值续问。V2 的后处理管道做几件事：
- 检测低价值续问：识别报告后的"还有问题吗"类填充消息并丢弃。
- 清理残留标记：移除部分
```代码块标记残留。 - 提取用户可见文本：
pick_user_facing_assistant_text从消息列表中挑出最终展示给用户的文本。 - 多轮对话保护：只在最后一条 HumanMessage 之后做清理，不影响历史消息。
11.4 PostgreSQL 持久化
V2 用 PostgreSQL 做两层持久化：
- Checkpointer：LangGraph 的状态检查点，支持断点续跑、时间旅行。
- Session Store：会话管理（会话列表、标题、消息计数、预览），通过
/api/sessions暴露。
两者在 lifespan 中初始化，应用关闭时按逆序清理（先 session store，再 checkpointer），确保资源释放有序。
🎫 十二、Backstage 集成：把 SRE Agent 嵌入开发者门户
让开发者在"自己的地盘"无缝使用 SRE 能力
12.1 为什么集成 Backstage
Backstage 是业界流行的开发者门户，团队用它统一管理服务目录、文档、CI/CD 入口。如果 SRE Agent 只能通过独立 Web UI 访问，开发者需要"跳出"日常工作流，体验割裂。
V2 的方案是把 SRE Agent 作为 Backstage 的一个插件嵌入，开发者在门户内即可调用告警分析、查工单、查链路等能力，无需切换系统。
12.2 集成方式：iframe 嵌入 + postMessage 身份传递
技术上，V2 的前端（Next.js + CopilotKit）被整体嵌入 Backstage 的一个 iframe 中。但嵌入带来一个关键问题：身份如何传递？Backstage 有自己的登录态，iframe 里的 SRE Agent 不知道当前是谁在用。
12.3 身份传递的重试机制
postMessage 是异步的，iframe 加载时机和父页面发送时机可能错开。V2 设计了多重试策略，确保身份一定能传到：
iframe 侧主动请求（PostMessageListener）：
- 加载后 500ms 发送
REQUEST_USER_ID给父页面 - 1500ms 再次发送（重试）
父页面侧主动推送：
- 父页面在多个时机尝试发送
SET_USER_ID - 重试间隔：0ms / 100ms / 500ms / 1000ms / 2000ms，共 5 次
双重保险：iframe 主动要 + 父页面主动给，即使某一方时序异常，最终也能对上。收到 userId 后存入 localStorage，并 reload 让后续请求携带身份。若 userId 未变化则跳过 reload，避免无谓刷新。
12.4 侧边栏导航 + 首页卡片入口
在 Backstage 中，SRE Agent 有两个入口：
- 侧边栏导航项：常驻左侧导航，点击进入 SRE Agent 全屏 iframe。
- 首页渐变色卡片：在 Backstage 首页以一张醒目的渐变色卡片呈现，作为"快捷入口"，降低发现成本。
12.5 CSP 配置
iframe 嵌入需要 Content Security Policy 放行。V2 要求在 Backstage 的 CSP 中配置 frame-src 允许 SRE Agent 的来源：
若未配置，浏览器会拒绝加载 iframe，表现为页面空白。这是集成时最常见的"看不见的坑"。
12.6 用户体验：无缝使用
对开发者而言，体验是无缝的：
- 登录 Backstage 后，点击多智能体卡片，直接进入对话界面，无需二次登录。
- 所有查询自动携带当前用户身份，后端按用户隔离会话历史。
- 会话持久化在 PostgreSQL，下次进入仍能看到历史对话。
- 分析结果可以直接在 iframe 内查看，也可以通过 AtlassianAgent 一键创建工单。
开发者无需学习新系统，在"自己的门户"里就拥有了 SRE 级别的排障能力。
12.5 钉钉 & 企业微信：把 SRE Agent 嵌入日常办公
sre-agent-im-adapter 是一个轻量级 IM 适配层，让多智能体的能力直接接入企业内部即时通讯平台。运维人员无需打开任何 Web 页面，在钉钉群或企业微信中 @机器人 就能完成告警分析、根因排查、工单创建等操作。
- 零切换成本——SRE 告警本来就在群里发，@机器人 直接分析，不用再切系统
- 多轮上下文——钉钉侧自动拼接被回复消息内容，支持连续追问（"这个服务最近的变更是什么？"）
- 即时反馈——收到消息立即回复"正在处理"，避免用户重复发送
- Markdown 输出——Agent 返回的结构化结果以 Markdown 格式渲染，表格、列表、加粗都能正常显示
12.5.1 架构模式
| 维度 | 钉钉 | 企业微信 |
|---|---|---|
| 连接方式 | dingtalk-stream SDK（长连接 Stream 协议） | 企业微信官方长连接（回调 URL 模式） |
| 认证 | K8s Secret 注入 AppKey / AppSecret | K8s Secret 注入 BotID / 密钥 |
| 回复格式 | reply_text() 即时确认 → reply_markdown() 最终结果 | reply_stream(finish=False) 中转 → reply_stream(finish=True) 终态 |
| 上下文支持 | ✅ 自动提取被回复消息内容拼接 | ⚠️ 当前仅传当前文本 |
| 消息去重 | ✅ msgId 缓存（上限 1000 条） | ✅ msgid 检查 |
| 超时控制 | 默认超时 | 约 570 秒（流式窗口余量） |
12.5.2 部署形态
K8s 中实际运行 多个 adapter 容器（共享 Pod 网络），通过集群内部域名访问后端服务：
dingtalk-adapter—— 钉钉机器人实例wecom-adapter—— 企业微信机器人（主环境）wecom-adapter-standby—— 企业微信机器人（备用环境）
凭证统一从 K8s Secret 注入为环境变量，CI/CD 通过 Pipeline 自动构建镜像、推送容器仓库、执行滚动发布。
🚪 十三、五种入口方式
CLI / Web UI / HTTP API / MCP Server / IM 机器人——总有一款适合你
13.1 MCP Server 的特殊之处
V2 通过 FastMCP 暴露一个 ask_sre_copilot 工具，让 VSCode、Cursor、Claude Code 等 MCP 客户端直接调用 SRE 能力。关键设计：
- 无状态 HTTP（
stateless_http=True）：每个 POST 独立，不依赖 MCP 层会话状态。多轮状态由后端 PostgreSQL 管理，不在 MCP 层暴露。 - lifespan 合并：FastMCP 子应用的 lifespan 必须与主应用一起进入，否则首次请求会报 "task group is not initialized"。
13.2 IM 机器人：钉钉 & 企业微信（⭐ 生产高频入口）
对于运维团队来说，IM 机器人可能是最高频的使用方式——告警本来就在群里发，@机器人 就能分析，零切换成本。详见 十二章·五节：IM 适配器详解。
- 钉钉群 → @机器人 → 发送告警文本 → 等待 Markdown 结果返回
- 企业微信 → 打开与机器人的对话 → 发送问题文本 → 等待结果返回
- 支持多轮对话（钉钉自动拼接被回复消息内容）
🔭 十四、可观测性：Langfuse 全链路追踪
确定性可回放——每一次分析都能复盘
14.1 为什么 Agent 需要可观测性
Agent 系统的"黑盒"问题比传统服务更严重：一次分析可能调用十几个工具、经过多轮 LLM 推理，如果结果不对，你很难知道是"哪一步想错了"。Langfuse 提供全链路追踪，把每一步都记录下来。
14.2 追踪的内容
- LLM 调用：每次模型调用的输入、输出、token 数、耗时。
- 工具调用：每个工具的名称、参数、返回值、耗时。
- 专家 Agent 调用：哪个专家被调用、传了什么参数、返回了什么。
- 回调传播：通过
callback_context在专家和工具间传播回调，确保追踪不断链。
14.3 确定性可回放
V2 的一个设计目标是"可回放"：给定相同的输入和工具返回，分析过程应当可复现。为此：
- 工具调用是确定性的（同样的参数同样的结果，因为是直查数据库/API）。
- LLM 调用的输入/输出被 Langfuse 完整记录，可以回放。
- PostgreSQL Checkpointer 保存每步状态，支持"时间旅行"到任意中间点。
这意味着：当一次分析结果存疑时，可以在 Langfuse 里回放整个推理链，定位"哪一步的 LLM 输出偏离了预期"。
🧭 十五、设计与演进
五大设计原则 · 五项优雅降级 · V1→V2→V3 路线
15.1 五大设计原则
| 原则 | 含义 |
|---|---|
| 最小上下文 | 工具返回聚合摘要而非原始数据，避免上下文爆炸 |
| 分层递进 | summary → samples → details，先给概览再按需深入 |
| 单一职责 | 每个工具有且仅有一个明确目的 |
| 优雅降级 | 外部依赖不可用时自动退化，而非整体崩溃 |
| 确定性优先 | 能用规则确定的不用 LLM 决策（如 TraceAgent 调用规则） |
15.2 五项优雅降级
- OpenSearch 不可用：日志/链路工具返回错误提示，Agent 转而依赖 Kubernetes 事件和指标推理。
- Prometheus MCP 超时：MetricsAgent 设置闸门，一次失败后跳过后续 PromQL，避免连锁超时。
- MCP Server 未启动：MCP 相关工具标记不可用，Agent 用 Native Tools 替代。
- PostgreSQL 不可用：Checkpointer 降级为内存模式，会话持久化暂停（重启后丢失）。
- Langfuse 未配置：追踪静默关闭，不影响业务功能。
每一项降级都确保"核心功能仍可用"，而非全盘失败。
15.3 V1 → V2 → V3 演进路线
✅ 十六、总结
回到最初的问题：V2 到底带来了什么？
16.1 核心价值
- 从单兵到团队：八个专家 Agent 协同，一次分析覆盖链路/指标/日志/集群/代码/工单全维度。
- 从查到写：不只是查日志，还能创建工单、沉淀文档、关联事件，形成闭环。
- 从割裂到无缝：Backstage 集成让开发者在门户内直接使用 SRE 能力，无需切换系统。
- 从黑盒到可回放：Langfuse 全链路追踪 + PG 持久化，每次分析可复盘、可审计。
- 从脆弱到韧性：五项优雅降级，外部依赖故障时核心功能仍可用。
16.2 V1 / V2 对比
| 维度 | V1 多智能体 | V2 深度智能体 |
|---|---|---|
| 协调方式 | Supervisor 路由 | Deep Agent 深度推理 |
| 工具调用 | 单轮 | 多轮循环 + 笔记累积 |
| 专家数量 | 6 个 | 8 个（+GitLab/Atlassian） |
| 技能系统 | 常驻系统提示 | 30 个技能按需加载 |
| RCA 流水线 | 单批 | 两批（日志先行 + 代码追溯） |
| 入口 | CLI / Web | CLI / Web / HTTP API / MCP |
| Backstage | 无 | iframe + postMessage 集成 |
| 持久化 | 内存 | PostgreSQL（Checkpointer + Session） |
| 可观测性 | 基础日志 | Langfuse 全链路 + 可回放 |
| 降级能力 | 有限 | 五项优雅降级 |
16.3 上线建议
- 先只读，后写入：初期只开启查询/搜索类工具，验证准确性后再解锁工单创建。
- 先 CLI，后 Web：内部先用 CLI 跑通 RCA 流水线，再开放 Web UI 给更大范围。
- 先单领域，后跨领域：先让单个专家（如 LogAgent）稳定运行，再启用 Deep Agent 的跨专家协同。
- 技能分批挂载：先挂核心排障技能（alarm-types、troubleshooting-patterns），再逐步加架构、CI/CD 类技能。
- 可观测性先行：上线前先配好 Langfuse，确保每次分析可回放、可审计。
- Backstage 集成最后做：在独立 Web UI 验证稳定后，再嵌入 Backstage，降低集成阶段的调试复杂度。
恭喜你看完了这篇长文！
💡 这篇文章覆盖了多智能体 V2的 16+ 个功能模块，从架构到工程实践，从告警分析到 Backstage 集成、IM 机器人。
👍 如果对你有启发，别忘了 点赞 + 在看 + 转发 三连！
🔔 关注获取后续更新：V3 规划、向量知识库、告警收敛等进阶内容。
📂 收藏本文，下次遇到排障场景时翻出来对照，事半功倍。