AIOps 智能运维 Agent 的 LangGraph 与 MCP 编排设计

拆解智能运维助手的接口层、配置层、LangGraph 状态机、多集群联邦 Agent、调度引擎和 MCP 工具解耦方案。

本文由《智能运维助手设计文档 v3.0.0》整理而来，已移除目录前模板页、版本页和前置信息；正文、截图、表格与操作步骤按博客阅读方式重新排版，并拆成 AIOps 系列。
系列导航：总体架构 · LangGraph 与 MCP 编排 · 部署、评估与测试

模块详细设计

接口层与配置层设计

接口和配置层作为整个系统的前期入口，配置层可以方便的对agent运行过程中的重要参数如大模型模型配置，agent工作流节点每个节点调用最大工具限制，第三方MCP接口配置

图4-1配置示例

联邦集群信息配置，think块展示模式，RCA节点分析是否启用ai工具调用分析等。

而接口层责负责请求api的设置，与路由控制。

图4-2 api接口示意

最主要的核心api接口如下

curl -G "http://10.2.0.48:30800/ask" --data-urlencode "q=集群 CPU和内存memory 使用率是多少，具体到每个node级别"
curl -G "http://10.2.0.48:30800/ask" --data-urlencode "q=我的集群有什么问题？"
curl -G "http://10.2.0.48:30800/federation/ask/v2" --data-urlencode "q=我想要知道 main 的内存使用率和 cluster-24 的 CPU 使用率"

分别对应了ask接口，query接口，和fedurate联邦接口。

Ask接口即为之前提到的4节点工作流深度分析并且给出运维报告的方式，而quey接口后台会走2节点工作流从layer-conclusion直接总结，因为query模式一般不需要深度的证据采集，并且为了提升效率如此设计。可以较准确的获取到如集群的cpu使用率，memory使用率。

联邦查询转发的接口到具体集群中还是走的之前ask/query接口不过在转发前嵌套了一层Agent用来意图识别将用户的请求转发到具体的集群中。

配置层设计

配置层的参数控制着agent运行过程中的具体边界条件比如最大运行工具数量，截断输出上限等。配置方式为通过k8s资源configmap的形式，挂在进入aiops的pod中。

图4-3 核心参数配置

在核心参数配置中包含了运行的大模型配置url，model类型和token。还有输出的日志级别以及ai自动修复功能。在之前的测试中发现如果使用较好的模型并且异常问题非常明显而且runbooks中有明确的修复方法和手段，有些时候LLM会自动执行命令将异常资源修复。通过该配置可以在系统提示词中附加一段额外的指令。这些核心参数在k8s中一以环境变量的形式存在，并且发挥功能。

Api接口

接口层的核心入口是FastApi，/ask请求走诊断完整工作流，/query走2节点快速查询流程，用于查询prometheus指标不进入evidence和rca节点。这两个接口都支持流式输出。

关于流式输出，直接使用holmegpt和langgraph去使用的时候，所有的后台过程包括工具调用thinking过程，以及大模型的返回都是被封装起来。用户的直观体验就是执行查询后会持续等待几分钟才会有全部的输出，整个个过程不够透明也不清楚是卡住了还是还在运行，为了理解agent运行过程的可解释性需要对agent的调用接口提供流式输出的能力。包括输出内容的阶段性吐出，不同节点之间的工具调用详细输出，大模型思考过程输出，节点间传递信息的具体内容输出。

之前无法实现是因为holmegpt框架的限制。这里的核心问题不是 HTTP 不能流式，而是 HolmesGPT 框架把推理过程封装在内部在 HolmesGPT 模式下，外层服务通常只能拿到这些粒度的信息：

• 最终回答文本。

• 部分日志。

• 部分工具调用日志。

• HolmesGPT 框架暴露出的高层事件。

但真正 token streaming 需要模型调用层在每个 token 或 message chunk 到达时，把增量内容暴露给上层。早期 HolmesGPT 作为上游框架时，服务层并不直接控制底层 ChatModel 的 stream iterator，也不能稳定拿到每个 token chunk。

因此第一阶段的优化目标是而是先让长时间诊断任务变得可观测。

这一阶段的核心做法是：API 仍然返回文本流，但服务层把工作流执行过程拆成一行一行的可读事件。

图4-4 事件流式输出

这个阶段的“流式”本质是行级/事件级，它解决了卡顿和不可观测问题，但还不是模型 token 级 streaming。模型在某个节点内部生成长文本时，外层可能仍然要等这一轮模型调用返回后，才能拿到完整 message 再输出。

后续阶段的流式输出设计：由于holemsgpt的框架限制，需要将ai调用能力从框架中解耦，开发Ai Call模块来替代holmegpt中的LLM CALL能力。从 HolmesGPT 内部调用迁移到自研 AICall，底层使用 LangChain / LangGraph 的 agent stream。这样可以实现对token级别的输出控制。核心链路为：

FastAPI StreamingResponse

-> HolmesService.execute_query_stream()
-> HolmesService._workflow_to_text()
-> WorkflowExecutor.execute_stream()

-> 后台线程运行 LangGraph workflow.stream()

-> 节点通过 event_queue 推送 node_lifecycle / thinking

-> AICall.call() 通过 agent.astream() 接收 updates + messages

-> 服务层把事件渲染为 text 或 SSE

同时节点内部的 AICall 会产生 thinking 事件：tool_start，tool_result，ai_message，ai_token，iteration_end，这些东西都可以被细粒度的控制和输出。

而token 级输出的关键在于当连续 token 到达时，服务层不会每个 token 都加一行前缀，而是在本段 token 流开始时输出一次：之后直接追加 token，直到下一个非 token 事件到来再换行。

if chunk_type == "messages":
token_msg, metadata = chunk_data[0], chunk_data[1]
if token_msg.content and metadata["langgraph_node"] != "tools":
push_event(stream_queue, "ai_token", node_id, content=token_msg.content)

message就是包含模型输出的token直接追加 token，直到下一个非 token 事件到来再换行。

以此来实现token级别的输出流式控制。

编排策略层

LangGraph状态机工作流

LangGraph 工作流模块是系统中实现结构化诊断流程的核心组件，负责将原本依赖大语言模型自由推理的诊断过程转化为可控、可观测的阶段式执行流程。该模块位于推理层内部，由 HolmesService 调度触发，在接收到用户请求后负责组织完整的诊断链路。其主要职责是将用户输入转化为结构化分析结果，并通过分阶段处理逐步完成问题定位、证据收集、根因分析与结果生成。模块输入为用户问题及上下文信息，输出为结构化诊断报告及中间分析数据。

该模块的核心设计理念是“状态驱动执行”。系统定义统一的 WorkflowState 作为全局状态对象，在整个工作流中进行传递和更新。最终在结果汇总节点中生成完整报告。每个节点只负责读取当前状态并输出增量信息，而不直接依赖其他节点，从而实现模块间的低耦合。

在问题定位节点中，用户输入问题“我的集群有什么问题”大模型通过调用MCP工具来查看异常的pod，异常的资源和event，以及调用fetch_runbook来补充自己的额外知识。通过初步采集工具结合自己的理解能力，识别问题所属的资源层级、关键对象以及潜在故障场景。该节点的核心作用是缩小问题空间，为后续步骤提供明确方向。将结果以结构化的形式传递下去。

在证据采集节点中，系统根据问题定位结果动态生成采集策略，首先要求evidence节点第一步输出一个plan用来规划根据上一节点得到的问题定位来制定一个证据采集计划，要采集什么证据，要查看什么资源，获取什么信息等。并调用执行层工具获取相关数据。与固定脚本式采集不同，该节点由模型参与决策，能够根据不同问题选择最相关的数据源。得到真实工具的输出后同样以结构化的形式存入state对象传递下去。所有节点共享 WorkflowState。每个节点只返回增量 new_state，LangGraph 合并到全局状态。

图4-5 Langraph工作流架构图

根因分析节点是工作流中最核心的决策环节，由于历史遗留问题，在之前的过程中我们会根据大模型自身的 能力为json结构体得到的evidence中给不同的证据打上标签比如critical,normal,等用来区别证据的重要程度。并且有打分机制。在该阶段RCA根因分析，他会根据上一节点的evidence输出的结构化证据和layr的定位证据综合考虑。输出一个根因分析的结构化输出，至少包含有

"phenomenon": "现象描述",
"evidence_inventory": [{{{{"id": "e1", "content": "内容", "source": "来源", "reliability": "高/中/低"}}}}],
"evidence_analysis": [{{{{"evidence_id": "e1", "raw_data": "原始数据（必须包含具体数值）", "interpretation": "含义"}}}}],
"causal_chain": {{{{"root_cause": "根因", "propagation": "传导", "direct_cause": "直接原因", "manifestation": "现象"}}}},
"root_cause_summary": "根因结论（引用证据和具体数据）",
"confidence": 0.0-1.0,
"primary_runbooks": ["上游已参考的 runbook 名称"],
"alternative_causes": [],
"limitations": "局限性"

尝试识别已知故障模式并输出确定性结果；在规则未命中或证据不足的情况下，大语言模型将参与推理过程，对问题进行补充分析。

在结果汇总节点中，系统将前序节点产生的结构化数据整合为最终输出报告。该节点不仅负责生成人类可读的诊断结论，还会对分析过程进行总结，包括关键证据、推理路径以及推荐的修复措施。

通过上述设计，LangGraph 工作流模块成功将原本不可控的大语言模型推理过程转化为结构清晰、可观测的阶段式执行流程。每个模块都单独运行一次LLM调用，每个node节点都有自己的prompt，并且最终的输出模板有标准化的结构输出方便形成模板。该模块不仅提升了系统的稳定性与可解释性，也为后续扩展规则引擎、多集群能力以及更复杂的诊断逻辑提供了基础支撑。在整个系统中，该模块是实现“可控智能诊断”的关键组件，也是当前实现最完整、最具代表性的核心模块之一。

多集群联邦agent

多集群联邦诊断模块是 Robusta AIOps 平台面向分布式 Kubernetes 环境设计的核心扩展能力，其主要目标是在多个独立集群之间建立统一的智能诊断入口，实现跨集群的信息聚合、问题分析与全局决策支持。该模块位于系统架构的协调层之上，通过统一接口屏蔽各子集群之间的差异，使用户能够以单次自然语言请求完成多环境诊断任务。模块输入为用户查询请求，输出为跨集群综合分析报告。

在设计理念上，。各子集群保持独立运行状态，拥有完整的诊断能力（传统模式或工作流模式），联邦层不直接执行底层运维操作，而是作为协调代理负责请求分发、结果收集与认知融合。通过agent to agent的能力实现。

该模块采用 FederationCoordinator 作为核心调度组件。协调器在系统初始化阶段加载联邦配置，构建子集群注册表，其中包含集群名称、访问端点、描述信息及启用状态等元数据。当用户通过联邦接口发起请求时，协调器负责解析查询目标并生成执行计划。执行计划定义了需要访问的集群集合、执行模式以及结果聚合策略，从而将单一用户请求转换为多个子任务。主要是内置实现了2个工具一个list cluster 一个query cluster实现。

为了适应不同的运维场景，模块设计了两种联邦执行模式：并发聚合模式与智能路由模式。并发聚合模式采用确定性执行策略，即系统默认向所有启用的子集群发送相同查询请求。协调器通过异步并发机制同时调用各子集群接口，并等待结果返回或超时结束。这种模式实现简单且结果覆盖全面，适用于全局巡检、健康状态统计及跨环境一致性检查等场景。在实现层面，系统基于 asyncio.gather 构建并发请求执行模型，共享 HTTP 连接池以减少网络开销，从而保证在多集群场景下仍具有较高吞吐能力。

图4-6 联邦查询架构图

在并发执行完成后，FederationAggregator 组件负责结果聚合与统一分析。该组件首先对所有子集群返回结果进行标准化处理，提取核心结论信息，包括问题摘要、根因判断和修复建议。同时记录失败节点及异常信息，以保证报告完整性。随后，聚合后的数据被提交给大语言模型进行跨集群综合推理，

与并发模式不同，智能路由模式引入 Agent-to-Agent 架构，使联邦层具备自主决策能力。在该模式下，FederationAgent 被设计为具备工具调用能力的 LLM Agent，其核心职责是理解用户意图并动态决定查询策略。Agent 首先分析问题语义，判断是否需要查询特定集群或多个候选集群，然后通过工具调用机制获取集群列表或触发单集群诊断。

为了支持智能路由能力，模块为 FederationAgent 提供标准化工具接口，包括 list_clusters 与 query_cluster 两类工具。前者返回当前系统中可用集群信息，用于构建认知上下文；后者负责向指定子集群发送诊断请求并返回核心结果。系统在执行多个 query_cluster 调用时自动启用并发优化，使模型层的多工具调用能够映射为底层的并行网络请求，从而兼顾智能性与执行效率。

在数据管理方面，多集群联邦模块采用“摘要入上下文、全文入存储”的策略。由于子集群返回的诊断报告通常体量较大，系统仅提取关键结论部分供联邦 Agent 推理使用，而完整报告则保存至本地报告存储目录。这种设计有效避免了上下文窗口被大量数据占用，同时保留了完整审计能力。用户可以通过报告接口访问历史诊断记录，实现问题追溯与经验复用。

HolmesgptService调度引擎

在执行路径控制方面，HolmesgptService 采用策略分发机制，根据请求内容动态选择不同的诊断模式。例如，当选择工作流模式时，请求将被提交至 LangGraph 工作流执行器；当启用联邦模式时，则交由 FederationCoordinator 进行跨集群调度。通过这种集中调度方式，系统避免了业务逻辑分散在多个模块中的问题，使整体流程更加清晰可控。

图4-7 holmesgpt service架构图

在交互体验设计上，HolmesgptService 同时承担流式输出协调职责。系统将诊断过程划分为多个阶段事件，并在执行过程中逐步向接口层发送状态更新，包括流程开始、节点执行完成、子集群返回结果以及最终报告生成等信息。

配置化知识外置

配置化知识外置模块是本系统实现 可扩展诊断能力与低耦合演进架构 的核心设计之一，其主要目标是将传统 AIOps 系统中硬编码在程序逻辑中的专家经验、诊断规则与上下文知识，并以配置化、结构化和可动态加载的方式进行统一管理。该模块使系统从“固定逻辑驱动”转变为“知识驱动”，从而支持不同业务场景、不同集群环境以及不同运维策略下的快速适配与持续演进。

在整体架构中，配置化知识外置模块位于 HolmesGPTService 调度引擎，在服务初始化过程中会将已经存在的runbooks的摘要信息注入到系统提示词中，配合专属的工具fetch_runbooks可以直接获取到存储的markdown文件。额外的runbooks内容承担着知识供给与上下文增强的角色。当调度引擎生成诊断任务或工作流节点执行请求时，该模块根据当前任务类型、资源对象、异常类别以及集群上下文信息，动态加载对应的知识配置，

图4-8 runbook额外知识库挂载示意图

该模块的核心设计理念是 “知识即配置（Knowledge as Configuration）”。系统将诊断知识拆分为多个可组合单元，例如诊断提示模板（Prompt Templates）、异常判定规则（Heuristics Rules）、指标解释说明（Metric Semantics）、以及操作建议策略（Action Playbooks）。这些知识单元统一采用 YAML 或 JSON 格式进行描述，并通过版本化管理进行维护

图4-9 一个runbooks示例

总体而言，配置化知识外置模块使系统从传统的“模型调用平台”升级为“知识增强型智能诊断系统”。它不仅提高了 Agent 推理的稳定性与可解释性，也为未来企业级知识沉淀提供了长期演进空间，是整个平台实现工程化落地与规模化应用的重要基础模块。

规则与执行工具层设计模块

结构化输出

在早期的使用过程中由于没有任何结构化输出，所有的内容都通过文本的形式注入到上下文中，由于除了提示词外会有大量的工具中间结果。在多轮调用工具结果之后会出现大模型理解能力下降，无法获取准确有价值的信息内容。因此必须使用结构化输出来规范节点之间通信的具体协议，使用规则的结构化输出可以有效的让大模型将注意力集中在重要的字段中，并且可以适配langchain后续middleware的中间件开发，提供更加复杂和符合的安全能力比如执行工具前人工确认，重要字段的手动抓取。

具体内容为，工具调用的直接输出是基于txt的，通过ai大模型的能力让它再给后续节点输出的时候传入结构化的信息，比如下图所示，里面包含了后续节点使用的必要内容。方便后续的节点更加全面的分析与定位。

图4-10 结构化json输出

MCP 调用与能力解耦架构设计

MCP 调用模块是 Robusta AIOps 平台实现 外部能力解耦与工具统一接入 的核心基础设施，其设计目标是在 Agent 推理系统与底层执行工具之间建立一个标准化能力层，使系统能够以可扩展、可治理、可独立演进的方式接入各种运维能力。本模块采用完全分离式架构设计，将 MCP（Model Context Protocol）工具运行环境从 HolmesGPT 与 AIOps 主服务中独立出来，通过统一的 MCP Server Manager 进行生命周期管理，从而避免工具逻辑与推理系统耦合。

在整体系统结构中，MCP Server Manager 作为独立服务运行，其职责并非执行诊断逻辑，而是将各种 MCP 工具统一转换为标准 SSE（Server-Sent Events）接口，供 HolmesGPT 调度引擎进行调用。传统 MCP 多基于 stdio 通信模式运行，难以直接在分布式环境中被多个服务共享，而本设计通过 mcp-proxy 将 stdio MCP 转换为 HTTP SSE 端点，使每一个 MCP 工具在网络层表现为独立服务，从而实现云原生环境下的可发现与可复用能力。

图4-11 mcp工具集合调用架构图

该模块的核心设计理念是 “能力服务化（Capability as a Service）”。系统中每一个 MCP 工具（如 Kubernetes 查询、Helm 操作、Prometheus 指标获取或日志检索）均被视为一个独立能力单元，并通过配置文件进行声明式管理。开发者只需在配置中定义 MCP 名称、运行方式（Python、本地脚本、npm 或 uv 包）、端口以及启用状态，启动器即可自动为其创建代理进程并暴露 /sse 接口。这种方式使新增工具无需修改 HolmesGPT 代码，仅通过配置扩展即可完成能力接入，大幅降低系统扩展成本。

调度引擎随后以统一协议发送调用请求，由 MCP Server Manager 转发至对应 MCP 子进程执行，并将结果以流式事件返回。该机制实现了推理层与执行层之间的协议统一，使 Agent 能够像调用函数一样调用分布式运维能力。

通过 ConfigMap 注入 MCP 配置，并由 Deployment 与 Service 暴露多端口服务，实现集群内部服务发现。这种设计保证开发与生产环境行为一致。

分离式 MCP 架构带来的关键优势之一是 系统稳定性隔离。由于 MCP 工具运行在独立进程甚至独立容器中，单个工具异常不会影响 HolmesGPT 推理服务。当某 MCP 出现崩溃或性能问题时，仅需重启对应服务即可恢复能力，而无需影响整体诊断流程。这种故障隔离能力对于 AIOps 平台尤为重要，因为外部系统（如 Kubernetes API 或日志系统）本身具有不稳定性。

此外，该设计还显著提升了能力治理与权限控制能力。通过集中化 MCP 管理层，平台可以对不同 MCP 进行启停控制、端口隔离以及环境变量注入，从而支持不同集群或租户加载不同能力集合。HolmesGPT 只感知能力接口，而不关心工具实现细节，实现真正意义上的能力抽象层。

总体而言，MCP 调用与能力解耦架构将系统从“内嵌工具调用模式”升级为“服务化能力平台”，实现了推理层、执行层与工具生态之间的彻底解耦。

接口设计

接口设计

接口层是 Robusta AIOps 平台与外部世界交互的统一网关。该层基于高性能的 FastAPI 框架构建，不仅负责基础的请求鉴权与路由分发，更核心的职责是抹平底层异构 AI 引擎的输出差异。

目前支持的api包含如下。

客户端请求首先进入 FastAPI 路由模块；随后请求被转发至 HolmesGPTService 调度引擎；调度引擎根据运行模式选择单集群工作流或联邦 Agent；最终通过 MCP 工具访问 Kubernetes、Prometheus 或日志系统并返回结果。

使用方式如下：

Ask接口

curl --no-buffer -G "http://HOST:30800/ask" \

--data-urlencode "q=我的集群有什么问题？"

Query

curl --no-buffer -G "http://HOST:30800/query" \

--data-urlencode "q=集群 CPU 和内存使用率是多少，具体到每个 node"

联邦查询

• /federation/ask

广播式诊断。

• 对所有已启用子集群发同一个诊断问题

• 适合统一巡检、统一比对

curl --no-buffer -G "http://HOST:30800/federation/ask" \

--data-urlencode "q=现在所有集群分别有什么问题？"

• /federation/query

广播式查询。

• 对所有已启用子集群发同一个查询问题

curl --no-buffer -G "http://HOST:30800/federation/query" \

--data-urlencode "q=各集群 CPU 使用率是多少"

• /federation/ask/v2

Agent-to-Agent 诊断。

• 主 Agent 决定查哪些子集群

• 可支持不同集群不同语义

curl --no-buffer -G "http://HOST:30800/federation/ask/v2" \

--data-urlencode "q=main 和 cluster-24 现在分别有什么问题？"

• /federation/query/v2

Agent-to-Agent 查询。

curl --no-buffer -G "http://HOST:30800/federation/query/v2" \
--data-urlencode "q=对比 main 和 cluster-24 的 CPU 使用率"