在 AI Agent 落地实践中，最常掉入的工程陷阱不是"能力不足"，而是过度设计。为了追求系统的严谨性，开发者常常不自觉地将简单的推理链路拆解成复杂的 Graph 状态机，结果反而引发了上下文割裂、编排冗余和模型幻觉。

本文将以一个真实的"运维诊断 Agent"重构为例，带你剖析过度设计的典型病症，并总结出一套行之有效的 Agent 设计方法论。

一、 过度设计的三大典型"踩坑"实录

在最初的架构设计中，为了实现一个"用户提问 -> RAG/查日志 -> 诊断报告"的链路，系统被设计为 Planner -> Executor -> Gatekeeper -> VerifiedInput -> Verifier -> Composer 的复杂多节点状态机。这种设计在实际运行中暴露了致命问题：

踩坑 1：用"编排复杂性"掩盖"推理能力不足"

问题：将"规划要查什么"和"去查"拆分成了独立的 Graph 节点。
本质：“思考要查什么 -> 去查 -> 看结果下结论”，这本该是同一个 ReAct 循环内交替发生的单步动作。强行把它们拆成外层 Graph 节点，导致主控逻辑被迫在 Graph 中不断来回传递状态，徒增极大开销，且割裂了推理的连贯性。

踩坑 2：误把"AI 基础能力"当成"独立节点"

问题：专门设计了一个 Composer 节点来总结诊断结论。
本质：总结结论是大模型的基础能力。在 ReAct 循环的终点（即模型认为已有足够证据时），直接在 Prompt 中要求输出结构化报告即可，根本不需要独立成 Node。

踩坑 3：误把"代码层工作"做成"LLM 节点"

问题：设计 Gatekeeper 节点用 LLM 去校验证据 ID 是否合法；设计 VerifiedInput 节点做数据清洗。
本质：参数校验、格式转换、数据过滤是确定性的代码逻辑。把它们做成 LLM 节点，要么浪费一次推理调用，要么让架构臃肿不堪。

二、 破局之道：回归"单 Agent + 强 Harness"

要解决上述问题，核心思路是：把推理还给 ReAct，把校验还给代码。

1. 核心执行层：合并为 1 个 ReAct Agent

砍掉 Planner、Executor、Composer 节点，合并为一个 DiagnosisAgent。它内部是一个 While 循环，自带规划、执行、总结能力，按"感知-决策-行动-反馈"的闭环运转。

2. Harness 约束层：代码接管确定性逻辑

将 Gatekeeper 和 VerifiedInput 降级为代码层的拦截器。

  • 工具执行前：用代码校验参数合法性。
  • 工具执行后：用代码清洗/压缩返回结果。
  • 输出阶段：用 JSON Schema Linter（0 LLM 调用）校验报告格式，不合规直接打回重试。

3. 验证层：异步轻量验收

如果业务对准确率要求极高，保留一个验收 Agent，但脱离主 Graph 链路异步触发。它只做交叉验证（如时间线一致性），不阻塞主流程。

三、 深水区排雷：解决单 Agent 的"上下文腐烂"

合并为单体 ReAct 后，立刻碰到了新问题：Executor 调用 7 次工具后，上下文线性递增，导致模型过度输出和幻觉。

这是典型的"上下文腐烂"。解决该问题的正道绝不是"退回多 Agent 架构"，而是重构上下文的流转方式：

  1. 上下文卸载：将工具调用的完整大段结果写入外部文件（如 refs/*.md），上下文里只保留简短摘要和路径索引。
  2. 工具层 RTK 机制：在工具返回结果前加一层 Harness 代码强制清洗。比如 1000 行日志，代码自动过滤出 5 行 ERROR 再返回给 Agent。
  3. 观察屏蔽与增量摘要：多轮调用时，将早期历史记录的原始返回折叠为摘要，保持上下文窗口"近期详细，早期摘要"的滑窗状态。

四、 终极拷问：到底什么时候才需要多 Agent / Graph？

架构演进的终极疑惑是：单 Agent 还需要 Graph 吗？什么时候该用 Supervisor 多 Agent 架构？

1. 单 Agent 需要 Graph 吗？

不需要重状态机编排。 如果是指"把规划、执行拆成多个独立 LLM 节点并连边"，坚决砍掉。单 Agent 的核心控制流只是一个带安全阀的 While 循环。唯一使用图编排框架（如 LangGraph）的合理场景是：需要"状态外化"和"可中断恢复"（如跑到一半存档、等待人工审批后断点续跑）。

2. 单 Agent vs Supervisor 多 Agent 怎么选型？

选型的核心标准不是"能不能指定不同模型"，而是任务的拓扑结构：

  • 线性深挖（选单 Agent）：任务一根筋往下查，前一步结论决定后一步查什么。拆给多 Agent 会丢失上下文连贯性。
  • 扇出汇聚（选 Supervisor）：任务可拆成互不依赖的子任务并行执行（如全局故障需同时查 DB、Redis、网关）。此时 Supervisor 派发子 Agent 并行跑，各自消化原始数据，只传结论摘要给主控。

两条硬性选型指标（触发其一才演进到多 Agent）：

  1. 工具数量溢出阈值：单个 Agent 工具超过 10 个，工具选择准确率断崖式下降。
  2. 上下文物理爆炸：即便用 Harness 代码清洗和文件卸载，业务上仍需保留复杂上下文才能推理，单窗口装不下。

五、 方法论沉淀：防止过度设计的 4+1 步检验法

如何在未来设计中自查是否过度设计？请遵循以下 4+1 步 SOP：

步骤 1：画出全链路流程图，合并"伪 Graph"节点

看哪些流程能总结成一次 ReAct Agent 的动作。如果相邻节点间没有人工审批或长时间异步等待，必须合并为单次 ReAct 动作。

步骤 2：单 Agent 上下文腐败检测

检查单 Agent 跑完任务后的上下文历史。如果工具返回结果全量累加，或注入了大量无关工具定义，就是过度设计。需实施"上下文卸载"和"工具懒加载"。

步骤 3：职责单一性与工具隔离审查

清点 Agent 的工具集。如果单个 Agent 同时握着跨域工具（如读文件、写代码、查 DB），必然产生幻觉。需按安全域和认知域拆分专才 Agent。

步骤 4：任务依赖与并行性分析

画任务依赖拓扑。如果是严格线性的，不需要多 Agent；只有真正存在"互不依赖且耗时"的子任务，才引入多 Agent DAG 并行编排。

附加准则：约束机制必须"下沉"

能写成 Linter 的约束不应停留在文档或 Prompt 里，更不该做成 Graph 节点。期望应编码为机制，机器强制永远比 LLM 推理更可靠。

结语

成熟的 Agent 架构，标志不是组件多么丰富、Graph 多么复杂，而是将模型能力接入可交付的工程运行时。把复杂性收敛到 Agent 的 System Prompt 和工具的代码层，用 While 循环驱动大脑，用 Harness 代码锁住手脚，你的系统才会既清爽又可控。