这两年 Agent 项目越来越多，但真正到生产环境跑起来之后，很多人的感受是：demo 好写，工程难做。Prompt 写得好坏是一回事，更让人头疼的是工具调用老出错、多步任务跑到一半就断了、状态乱成一锅粥。我自己从几个原型项目踩到生产项目，最深的体会是——Agent 工程能不能稳定落地，关键不在于选哪个模型、调哪条 Prompt，而在于你怎么设计那层“控制 Agent 行为的工程结构”。圈子里把这套结构拆成三层：Harness（支架）、Loop（循环）、Graph（图）。这篇文章就把这三层从头到尾拆开讲讲，包括每层到底解决什么问题、生产环境里怎么落地、以及那些文档里不写但你一定会踩的坑。
1. 三层架构的定位与整体思路
1.1 Harness、Loop、Graph 分别是什么
先说结论。Harness 是 Agent 运行的“环境边界”，Loop 是 Agent 行动的“驱动引擎”，Graph 是 Agent 决策的“路径规划器”。这三层不是可选的锦上添花，而是从工程角度把 Agent 从“一段调用模型 API 的脚本”升级成“一个可维护、可观测、可控制的生产系统”的必由之路。
Harness 在英文里是“挽具、马具”的意思，引申到 Agent 领域，指的是你给 Agent 搭的那套基础设施：模型接口、工具注册表、上下文管理、安全边界、日志追踪。它相当于操作系统里的内核，Agent 的所有能力都跑在这个“底座”上。没有 Harness，Agent 就是裸奔的模型调用；有了 Harness，模型才有一个稳定的环境去感知工具、调用能力、记录行为。
Loop 则是 Agent 的运行循环。模型不是一次性输出答案就完事的，它往往需要“思考 → 调用工具 → 观察结果 → 再思考”这样的多轮迭代。这个反复执行的过程就是 Loop。很多生产事故恰恰出在这里——循环没有超时控制、没有最大迭代次数、没有异常恢复机制，结果 Agent 在同一个错误工具调用上反复打转，白白消耗 Token 直到预算烧光。
Graph 是把 Agent 的决策过程从“自由发挥”变成“有路径可循”的编排层。你可以把 Agent 的任务拆成多个节点，比如“意图识别 → 信息收集 → 计划生成 → 工具执行 → 结果验证”，每个节点之间用边连接，形成一张有向图。Graph 的意义在于：不是每一步都让模型自由决策，而是让模型在允许的路径范围内选择，这样既保留了大模型的灵活性，又把不可控性关进了笼子里。
1.2 为什么三层缺一不可
很多 Agent 框架（比如 LangChain、LlamaIndex）其实都内置了这三层结构，只是它们把它们包装成了不同的接口。我见过一些团队只用了“模型 + Prompt”就开始做 Agent，结果项目到后期维护成本极高，因为所有逻辑都揉在 Prompt 里，出问题根本无从排查。
打个比方，Harness 是房子的地基和管线，Loop 是房间里的暖气系统（持续供热），Graph 是房间之间的走廊和门（决定你怎么从一间屋走到另一间屋）。没有地基，房子塌；没有暖气，人冻死；没有走廊，房间之间无法连通。生产环境里的 Agent 也一样：没有 Harness，工具调用混乱、上下文溢出、安全问题频发；没有 Loop，Agent 只能做单轮决策，无法处理需要多步操作的任务；没有 Graph，Agent 决策路径完全由模型自由发挥，既不可预测也不可审计。
从另外一面看，这三层也是从“最简单可用的 Agent”到“生产级 Agent”的三次演进。第一步，你用一层 Harness 包住模型 API，实现“一次调用、一次回答”；第二步，你加入 Loop 让它能反复调用工具；第三步，你用 Graph 把复杂的任务拆解、编排。每一层解决的都是上一层的痛点，缺了哪一层，系统都会在未来某个时刻要你还债。
1.3 这套架构适合谁、用在哪儿
三层架构不是银弹，它适合任务复杂度中等偏上的场景。如果你的 Agent 只是做一个“根据提问返回固定格式回答”的聊天机器人，三层架构是杀鸡用牛刀；但如果你的 Agent 要处理多步骤任务，比如“从邮件中提取需求 → 生成 SQL → 查询数据库 → 汇总结果 → 发送报告”，那没有这三层结构，你很难保证稳定性和可维护性。
我实际用下来，比较典型的适用场景有三类。第一类是自动化业务流程，比如客户工单处理、数据报表生成、内容批量生产；第二类是智能编码助手类工具，这类工具往往需要多轮代码检索、读写、测试；第三类是需要对接多个外部系统、复杂业务逻辑的“数字员工”，比如需要同时操作 CRM、ERP、知识库的搜索问答系统。这三类场景的共同特点是：任务步骤多、工具调用多、决策路径不唯一，恰好是三层架构最擅长的战场。
2. Harness 层深入解析：Agent 的骨架与安全边界
2.1 Harness 的核心组成模块
Harness 是 Agent 的“躯体”，它决定了 Agent 能调用什么工具、能看到什么上下文、行为有多可控。一个完整的 Harness 至少包含五个模块：模型接入层、工具注册表、上下文管理、安全策略与审计日志。
模型接入层解决的是“怎么跟模型对话”的问题。这个模块要处理模型 API 的封装（比如 OpenAI、Claude、DeepSeek 的统一接口）、请求重试、超时控制、Token 计数与成本控制。不要直接在一个 Agent 项目里到处调用模型 API，那样你后面想换模型、加缓存、做限流，会改到吐。我在自己项目中就把模型调用全部收敛到 Harness 的一个 provider 层，换模型只改一份配置。
工具注册表是 Harness 里最关键的模块之一。Agent 要调用外部能力，需要把工具（比如数据库查询、API 请求、代码执行、网页抓取）以某种结构化的方式注册进来。每个工具至少要包含：工具名称、功能描述、参数 Schema、执行函数、错误处理策略。工具的名称和描述一定要写得非常清晰，因为这些会直接被模型看到并用于决策。
上下文管理模块负责拼装发送给模型的消息序列。这里最典型的问题是上下文溢出——模型能处理的 Token 有限，你不能无限塞东西。Harness 要设计一套上下文压缩策略，比如：把历史对话摘要化、只保留最近的 N 轮、把工具结果过滤后仅保留关键字段。我见过不少项目在原型期不重视这块，上线后对话稍微长一点就开始报错，这就是 Harness 没做好。
安全策略与审计日志则是 Harness 的“守门员”。比如：限制 Agent 只能调用白名单内的工具、对工具输入做参数校验、对外部 API 返回的内容做脱敏、记录每一步操作的日志供事后追溯。凡是涉及生产环境的 Agent，安全策略绝不可以省。
2.2 Harness 与 Agent 框架的区别
很多人会混淆 Harness 和 Agent 框架（比如 LangChain、AutoGen、CrewAI），我简单梳理一下我的理解。框架是一个“工具箱”，它提供了很多现成的组件和抽象；而 Harness 是你在具体项目中搭建出来的“运行环境”，它不一定是通用产品，更多是跟你的业务深度绑定的一套工程实现。
用造汽车来类比：Agent 框架是标准件供应商，提供轮胎、发动机、仪表盘；Harness 则是整车厂的总装线，你要决定怎么把这些标准件跟你的底盘、车身、电气系统整合到一起，还需要加装安全气囊和定位系统等专属设备。所以，即使你用了 LangChain，你仍然需要花大量精力去搭自己的 Harness——配置工具的注册逻辑、裁剪上下文、设定安全规则，这些在框架层面只会给你半成品。
我自己早期项目就是直接把 LangChain 当 Harness 用，结果发现框架自带的能力跟业务需求永远有种“隔靴搔痒”的感觉，最后不得不自己封装了一层。所以我的建议是：框架可以当库用，但 Harness 一定要自己亲手搭，而且越贴合业务越好。
2.3 搭建 Harness 时的五个实操要点
第一，工具的 Schema 定义要严格，最好用 JSON Schema 规范。你给模型提供的工具参数结构越清晰，模型误用工具的概率越低。我在实际项目中见过模型把字符串参数填成数字、把必填参数漏掉、甚至把工具名拼错，这些都是因为 Schema 不够严谨。
第二，上下文管理者必须把“写入什么”和“丢弃什么”的规则显式化。我给每类消息都分配了预算，比如系统提示词固定占 1000 Token、工具结果是按需截断替换、对话历史按摘要保留。如果没有这个预算意识，模型输出质量和成本都会失控。
第三，工具执行必须做超时和重试。真实场景下，外部 API 随时可能超时、返回异常。Harness 层要对每个工具调用设置超时，超时后根据策略做重试或直接返回“工具不可用”给模型，让模型走兜底路径，而不是卡死在工具调用上。
第四，日志要结构化。每轮 Agent 运行都要记录：模型输入、工具入参、工具出参、耗时、成本、决策链路。后续排查问题时，这几点信息缺一不可。我在生产环境里查线上问题时，发现很多团队只看结果不看过程，一旦 Agent 行为异常只能靠猜，就是因为日志不达标。
第五，安全策略要能在 Harness 层统一拦截统一处理，而不是散落在每个工具函数里。统一拦截的好处是，你能够对工具的调用频率、调用范围、参数合法性做全局控制。比如我有一个 Agent 项目，里面需要对接公司内部的敏感系统，我在 Harness 层加了一个“工具白名单 + 字段脱敏”机制，所有工具的出入参都过这一层，既统一又安全。
3. Loop 层深度解析：Agent 的运转引擎与循环控制
3.1 从单轮调用到多轮循环的演进逻辑
没有 Loop 的 Agent 本质上只是“一次模型调用”。模型拿到用户输入，推理，输出结果，结束。这样的 Agent 能做的非常有限——它不能查资料、不能运行代码、不能去数据库里拉数据。为了让 Agent 具备“动手能力”，工程上最重要的一步就是引入 Loop：让模型可以多次跟环境交互，每次交互之后根据反馈决定下一步动作。
一个最基本的 Agent Loop 长这样：模型收到任务 → 选择工具（或直接回答） → 执行工具 → 把工具结果返回给模型 → 模型再决策，循环往复，直到模型认为任务完成（或触发终止条件）。这个循环看起来简单，但工程上要实现好它，非常考验细节。因为你面对的是一个概率模型，它每一步的决策都不是 100% 可靠的，你的循环必须有足够的容错能力。
我想强调一个观点：Loop 的设计本质上是“把模型的不确定性关进可控的循环里”。模型可能在某一步走偏，但它走偏后，你给它反馈让它纠正；模型可能在某一步反复横跳（选了工具 A，然后又想换 B，换完又想回 A），你的循环要有防抖机制；模型可能陷入死循环调用同一个工具，你的循环必须有硬性的迭代上限。这些都是 Loop 层的核心工作。
3.2 三种主流 Loop 模式对比
第一种是 ReAct 模式（Reason + Act）。模型在每一轮先“思考”再“行动”，把思考内容作为下一轮决策的依据。ReAct 适合绝大多数轻量级任务，实现简单、效果直观，是 LangChain 等框架默认支持的 Loop 模式。缺点是自由度太高，模型容易在思考上绕圈子；如果 Prompt 控制不好，每一步都会浪费大量 Token。
第二种是 Plan-and-Execute 模式。先让模型规划任务步骤，然后逐步执行。每一步执行时，都以“逐步执行计划中的一个步骤”为目标，而不是重新思考整个任务。这种模式适合复杂度高、步骤多的任务，因为模型先列计划，然后按计划推进，整体路径可控性更强。缺点是如果计划本身不准确，执行会跟着错下去，所以往往需要额外的“计划校验节点”。
第三种是 Reflection 模式，也叫自我修正循环。模型执行完结果后，由一个“评审者”（可以是同模型或另一个模型）对结果进行评估，如果不过关就反馈给执行者修改。这个模式很适合写代码、写文章等生成类任务，质量有明显提升，但代价是成本成倍增加。实际项目中，我不会全程都开 Reflection，通常只在最后一步做一次质量校验，性价比最高。
三种模式不是互斥的，可以在一个 Graph 层里混合使用。我常用组合是：开头用 Plan-and-Execute 拆解任务，中间用 ReAct 做逐步执行，结尾用 Reflection 做结果校验。这个组合覆盖了“规划 → 执行 → 质检”的完整链路，生产稳定性比只用单一模式高出一大截。
3.3 Loop 的关键参数与退出条件设置
Loop 设计得好不好，最直接的检验就是退出条件是否完善。一句话：永远不要把“模型说它完成了”当作唯一的退出条件。我建议至少设置四类退出条件。
最大迭代次数是底线，必须设置。按我的经验，常规任务迭代 5~10 轮就应该能完成；如果你发现任务经常需要 20 轮以上，那大概率是 Prompt 设计或工具划分有问题。硬性上限我给的是 15 轮，超过就强制终止，并把现场日志保存下来。
超时控制同样不能省。如果你的 Agent 是在线服务，每一轮调用模型的时间加起来可能变成几十秒甚至几分钟。我会为整个 Loop 设置一个总时间上限（比如 60 秒），防止 Agent 长期占用计算资源。超时后不是让用户干等，而是返回“任务处理超时，稍后重试”或把任务降级到人工处理通道。
连续无效行动检测是防死循环的关键。当模型连续 N 次调用同一个工具、或者连续 N 次输出格式非法、或者连续 N 次行动都没有产生有效信息更新时，强制截断并转人工或换一条路径。这个机制是我在生产环境对比后加的，效果显著。
人为干预通道虽然不常提，但生产环境必须有。Loop 跑着跑着，如果发现短时间内消耗了超过预期成本，必须能中断修改再恢复执行。我通常在 Harness 层预留一个人工审核开关，当 Agent 要执行“高风险工具动作”（比如发邮件、删数据）之前，强制等待人工确认。这本质上也是一种“安全退出条件”，牺牲了一点自动化率，换来了保险。
3.4 Loop 的状态管理与记忆机制
Loop 的每一轮都需要维护“状态”（State）。状态包含当前任务目标、已执行的步骤、工具返回的结果、临时变量等。没有好的状态管理，Loop 就是无头苍蝇。我在实践中根据任务类型选择不同的状态载体：简单任务用全局字典，复杂任务用图数据库或者内存缓存。
记忆机制是 Loop 层另一个重头戏。所谓记忆，就是让 Agent 能够引用“之前步骤的信息”。最常见的实现是把历史步骤摘要注入到后续每一轮的系统提示词里。有一个关键坑：直接把所有历史记录一股脑塞进去，上下文很快爆掉。我通常的做法是“分窗口记忆”——最近的 3 轮完整保留，之前的步骤用摘要压缩，摘要本身超过阈值再分层压缩。这样循环再长，输入成本也不会线性上涨。
需要特别提醒的是，状态管理必须考虑并发场景。如果你的 Agent 同时服务多个用户请求，绝不能用全局变量去存某个任务的状态，否则数据会互相污染。这轮提这个坑，是因为我见过不止一个团队在并发测试时发现任务 A 的工具结果跑到了任务 B 的上下文里。解决方案是给每个任务分配独立的 Session ID，Loop 的所有状态都挂在 Session 内部。
4. Graph 层深度解析：Agent 的路径规划与编排策略
4.1 Graph 层的角色：从“自由发挥”到“有限路径”
Graph 层是三层架构里最像“架构”的部分，因为它让 Agent 的决策路径变得可设计、可控制、可审计。没有 Graph 时，Agent 在一轮 Loop 里可以任意选择工具、任意切换意图，路径不可预期；有了 Graph，Agent 只能在预设的“节点”之间转移，每个节点执行一个明确定义的子任务。
我举一个实际项目的例子：做一个会议纪要 Agent，接收到一段录音转文字后要输出会议纪要和待办事项。如果只用 Loop，Agent 会自由地决定怎么处理这段文字，可能出现“先摘要、再提取待办、但摘要质量差、然后重新摘要”这类混乱路径。用 Graph 之后，我把流程固定成四个节点：文本清洗 → 信息抽取 → 纪要生成 → 校验输出。每个节点内部可以有自己的 Loop（调用模型来分析），但节点之间只能按固定方向流动。这样路径清晰，执行可预期，出了问题也知道该查哪一段。
Graph 层的设计原则是：节点越多，控制越强，但灵活性越低；节点越少，灵活性越高，但不可控性也越高。我的经验是，不要一开始就画一张很复杂的大图，先把任务拆成 3~5 个核心节点，跑通了再逐步细化。过早的设计过拟合，改起来成本极高。
4.2 基于 DAG 的编排与条件路由
Graph 的实现通常依赖有向无环图（DAG）。每个节点是原子任务，边定义了执行顺序，节点间的流转条件可以由规则（比如输出字段匹配）驱动，也可以由模型做主（比如让模型判断“下一步该走哪个分支”）。我在项目中把这两种方式称为“硬路由”和“软路由”。
硬路由适合逻辑明确的分支，比如“如果上一步没提取到关键字段，走修复节点；否则直接进入生成节点”。这种路由不涉及模型推理，速度快、可靠、易排查。软路由适合意图识别类场景，比如“让模型判断用户是想查询数据还是想生成报告，然后选择对应的处理子图”。软路由灵活，但有概率出错，所以要配合置信度阈值，置信度低时就进入“询问澄清”节点，让用户确认意图。
Graph 层还要考虑“回退”。比如执行到第 4 个节点时失败了，是回退到第 3 个节点重试，还是直接跳到失败处理节点？我在生产中的策略是分级回退：轻微错误回退一步重试，中等错误回退到规划节点重新规划，严重错误直接终止并触发人工告警。这个分级回退策略，极大提升了 Agent 在复杂任务上的最终成功率。
4.3 状态共享与信息传递设计
Graph 的每个节点虽然职责不同，但它们处理的是同一个任务，所以必须共享状态。在设计 Graph 时，我会先定义一个“全局状态对象”，里面放任务的原始输入、当前进度、各节点的输出摘要、临时变量池。节点读写状态不是自由的，而是通过接口，避免节点之间产生隐式耦合。
信息传递有一个常见误区：节点之间直接传长文本原始结果。这样做的后果是状态体积爆炸，而且后续节点的上下文被无关信息污染。我通常会为每个节点定义“输出摘要”，比如信息抽取节点只输出“结构化字段（时间、地点、人物、事项）”，纪要生成节点只接收这些字段而不是整段原文。这样状态精简，上下文干净，模型在后续节点里也更容易抓住重点。
在设计信息传递时，还要考虑“失败节点”的状态留存。不要让失败节点的输出残留到后续节点，否则错误会被不断放大。我的做法是：每个节点开始时先把全局状态做一次快照，节点结束时对比快照与当前状态，只保留预期变更，异常变更直接丢弃。
4.4 Graph 的可观测性与调试
Graph 层最大的好处之一就是可观测性好。因为路径是显式的，你可以把每一步执行情况用日志记录成一条“执行轨迹”：进入了哪个节点、输入了什么、输出了什么、耗时多少、成本多少、路由条件是什么。这可比纯 Loop 模式下看一条长对话日志要直观得多。
我实际调试时常用的手段是“Graph 可视化”。把每次执行后的 DAG 路径渲染成一张图，一眼就能看出 Agent 是不是绕了远路、在哪一步出过错、哪一步重复执行了。可视化工具我用的是开源的 Graphviz 或 D3.js，不需要很复杂，只要能还原执行拓扑就够了。
此外，Graph 层还方便我做“路径级别的 A/B 测试”。因为节点是模块化的，我可以给同一个节点设计两个版本的 Prompt 或两套工具，然后对比它们在相同任务上的成功率、耗时、成本。没有 Graph 的话，这种对比很难做干净，因为循环里的变量互相干扰。
5. 三层架构的组合实战：从零搭建一个生产级 Agent
5.1 选型：自研还是用框架
经常有人问我：搞这套三层架构，到底应该自己写还是用现成框架？我的回答是：框架可以用，但不能全依赖。比如你用 LangGraph，它本身就把 Graph 和 Loop 都封装好了，但 Harness 层仍然需要自己搭；你用 CrewAI 能快速搭建多 Agent 协作，但一旦涉及复杂的业务安全策略，还是得自己写扩展。
我目前的偏好是“轻框架 + 核心自研”：集成层用 LangGraph 做 Graph 的骨架，工具管理和上下文管理完全自研，模型层用统一 Provider 接口。这样做的好处是，既有框架帮你处理图的状态流转和持久化，又能保证 Harness 层的业务逻辑完全可控。如果你对 LangGraph 不熟，直接用 Python 或者 TypeScript 手写一个简单的 DAG 引擎也不难，核心也就一百多行代码。
模型选型上也说两句。目前我用得比较多的是 DeepSeek 和 Claude：DeepSeek 性价比高，适合中长文本处理、批量任务；Claude 在工具调用和代码生成上表现更稳，适合对质量要求高的场景。二者都可以无缝接入同一套 Harness，因为我的 Provider 层把接口统一了。
5.2 多 Agent 协作场景下的三层架构调整
三层架构不仅适用于单个 Agent，也适用于多 Agent 协作。多 Agent 场景里，常态是有一个“主控 Agent”（Supervisor）负责全局规划，下面挂多个“执行 Agent”（Worker）分别处理不同领域任务。Graph 层这时候需要升级为“子图”机制：主控是一个大的 DAG，每个节点内部又可以挂一张子 DAG，子 DAG 由独立的 Agent 负责。
我实现过一个典型的多 Agent 系统：主控 Agent 拿到用户需求后，先做任务分解，然后分别调度“SQL 查询 Agent”、“文档检索 Agent”、“数据分析 Agent”、“报告撰写 Agent”，最后汇总结果。在这个架构里，主控用 Graph 控制节拍，每个 Worker 内部又有自己的 Harness 和 Loop。全局路由靠 Graph，局部执行靠 Loop，所有 Agent 的输入输出统一走主控的全局状态池，避免信息孤岛。
这里有个容易踩的坑：多 Agent 之间如果直接互相调用，最终会形成一个网状调用关系，导致状态同步和排查问题都非常痛苦。正确做法是：所有 Agent 只跟主控通信，不直接互相调用。主控负责把信息分发给对应的执行 Agent。虽然多了一层转发，但逻辑结构清晰了不止一个量级。
5.3 生产实践案例：DeepSeek 客服 Agent 的三层装配
拿一个我实际跑过的案例来说明。这是一个面向海外用户的客服 Agent，后端接 DeepSeek 模型，核心任务是根据用户的问题查询 FAQ 知识库、查询订单状态、处理退换货申请。任务不算特别复杂，但因为涉及外部 API 调用和真实用户数据，稳定性和安全边界要求很高。
Harness 层，我注册了三个工具：知识库查询（接收关键词和类目，返回文档片段）、订单查询（接收订单号，返回订单状态和物流信息）、退换货申请（接收订单号和原因，写入工单系统并触发通知）。所有工具的入参都做严格校验，退换货申请还额外加了一道人工确认门槛——只有用户明确确认过信息，Agent 才能提交。
Loop 层，我使用了 ReAct 模式，最大迭代 8 轮，单步超时 10 秒。每轮循环后把工具结果摘要注入上下文，摘要长度限制在 200 字以内。如果 8 轮还没完成，Agent 自动降级为“转人工客服处理”并附上完整对话记录，避免用户在线上被无限拖延。
Graph 层，我用 LangGraph 把流程拆成五个节点：意图识别 → 信息收集 → 方案匹配 → 执行动作 → 结果反馈。意图识别是软路由，置信度低于 0.7 就进入澄清节点让用户补充信息；方案匹配是硬路由，根据信息收集节点的结构化结果选择查询、申请还是推荐。
这套架构上线后，一次完整对话的平均成本从最初单轮模型调用的 0.02 美元涨到了 0.06 美元，但成功解决率从不到 60% 提升到 90% 以上，而且每一条执行轨迹都能回溯。这个数据对比充分说明三层架构在生产中的价值。
5.4 成本、延迟与稳定性的取舍方案
三层架构虽然好，但一定会带来额外的成本和延迟。Graph 层每一次路由决策可能都要多调几次模型，Loop 层每多一轮都要多花 Token，Harness 层的日志和状态管理也会消耗计算资源。所以生产环境里需要一组合适的“降本增效”策略。
延迟优化上，我的做法有几种：一是把硬路由能解决的问题全部用规则做完，避免软路由反复调用模型；二是给模型配置较低的推理温度（0 到 0.3），减少随机性，让输出更稳定；三是使用流式输出和异步并行，能并行的节点尽量并行执行，比如多个 Worker Agent 同时查询不同的数据库，而不是串行等待。
成本优化上，建议把任务分成“高中低价值”三类，分别用质量不同、成本不同的模型。低价值任务用 DeepSeek 或更小的模型，高价值任务才调度 Claude。上下文也要控制，上面提过的摘要策略能省非常多 Token。我在实际项目中，通过把大段工具结果换成摘要，单次任务的 Token 消耗减少了 40% 左右且不影响效果。
稳定性优化上，最重要的原则是“宁可失败降级，不要无限重试”。Agent 执行失败几次后就该降级，而不是反复试探。我在 Loop 退出条件里加了一条：同一工具失败超过 3 次，强制走人工处理。这样既保证了用户体验，也让系统能及时止损。
6. 生产中的真实问题与排查手记
6.1 常见故障现象与定位方法
先列一个我从多个项目里整理出来的高频故障表。
| 故障现象 | 可能原因 | 排查切入点 |
|---|---|---|
| Agent 反复调用同一个工具 | 工具结果未被有效利用，模型陷入循环 | 检查工具结果是否摘要过于精简，或者 Prompt 里缺少“停止条件”说明 |
| 上下文溢出 | 工具结果未经收敛，历史记录无限膨胀 | 检查上下文管理策略，确认摘要和裁剪规则是否生效 |
| 工具参数错误 | 工具的 JSON Schema 不严格，描述不清晰 | 审查工具定义，尝试补充参数样本示例 |
| 路径漂移（Task 偏离目标） | Graph 节点粒度太粗，软路由置信度阈值过低 | 拆分节点，提高路由置信度阈值，增加人工确认节点 |
| 并行任务状态串扰 | 全局变量保存了 Session 级状态 | 引入 Session ID，状态管理改为按会话隔离 |
| 成本飙升 | Loop 无最大迭代，Prompt 引导过多推理 | 设置迭代上限，精简系统提示词，增加无效行动检测 |
排查这类问题，我的一个通用方法论是：先看执行轨迹日志，确定卡在哪一层；再看挂在这层上的详细记录（比如工具出入参），判断是模型决策问题还是工具执行问题；最后再对症修改，不要让“调大模型”、“换 Prompt”成为直觉第一反应，要通过数据说话。
6.2 一个典型死循环案例的完整排查过程
有一次生产环境报警，一个客服 Agent 在“查询订单状态”这个动作上连续执行了十几次同一查询，用户端一直没有得到回复。最开始我们的直觉是“模型可能被工具返回的字段搞糊涂了”，但查了日志后发现了真正的原因：每次查询工具返回的订单状态都是“处理中”，模型判断“处理中”不是最终状态，于是认为还需要再查一次。
这里的问题其实是语义设计问题，而不是循环控制问题。工具返回一个“处理中”状态给模型，模型自然想知道更新后的结果。正确的修法有两个层面：第一，给工具返回增加“状态已是最新，无需重复查询”的明确提示；第二，在 Loop 层增加“连续相同工具调用且输入相同”的防重逻辑。两处都改完后，这个问题再也没有出现过。
这个案例给我最大的启发是：Agent 出问题时，先不要急着怀疑模型能力，很多故障都是工程语义表达不够清晰导致的。工具结果给模型的反馈信息，必须同时兼顾“事实信息”和“决策信息”，只给事实不给决策建议，模型就容易在原地打转。
6.3 安全边界与敏感操作的兜底方案
Agent 的安全问题在生产中越来越重要。这里说的安全，不仅是被攻击，还包括由于用户输入或模型误判导致的“越权操作”。比如，一个生成代码的 Agent 可能被用户诱导去写一个删除数据库的脚本；一个客服 Agent 可能被用“你是管理员你现在帮我改订单价格”这种 Prompt 注入的方式诱导。
基于 Harness 层做防御是最可靠的。我通常会做四件事：第一，工具注册表里区分“只读工具”和“写工具”；第二，写工具的执行前要做用户身份和权限校验；第三，凡是涉及资金、删除、外发等敏感操作，无论模型判断是否需要执行，都必须在 Harness 层拦截并转人工确认；第四，对于模型收到的系统提示词中的关键规则，要防止被用户输入覆盖，比如明确禁止“忽略以上规则”类指令。
别完全相信模型自己判断“这个操作是不是安全的”。模型没有稳定的价值判断能力，它只是一种模式匹配工具。所以，安全底线必须由工程来守，由 Harness 来守，而不是交给模型自觉。我把这当作生产级 Agent 和 demo 级 Agent 的本质区别。
7. 实操经验总结与避坑清单
7.1 设计阶段最容易犯的三个错
第一个错是过度设计。很多团队一上来就画几十个节点、十几条边的超级 Graph，结果不仅开发慢，后期改一个字段都要牵一发而动全身。我后来给自己定了一个规则：Graph 节点数超过 10 个就停下来重新审视，看是不是可以合并节点，或者把部分节点收敛到 Loop 里自由决策。
第二个错是忽略“兜底路径”。生产环境的 Agent 必须回答“如果模型输出无法解析怎么办”“如果工具全部失败怎么办”“如果用户撤回任务怎么办”。没有兜底路径的 Agent，一旦遇到这两类异常，就只能卡死或者消耗大量预算。
第三个错是测试集太窄。很多 Agent 项目测试只用几条精心设计的样例，覆盖不到真实用户的长尾表达。我建议生产上线前，至少要准备 100 条真实用户输入来回归测试，其中包括模糊意图、超长输入、生僻缩写、乱码文本这些“反常规”样本。否则环境一上线就会原形毕露。
7.2 迭代阶段最值得投资的三个能力
排第一的是可观测性。在 Agent 的 Harness 层尽早接入轨迹追踪、Token 计数和成本报表，越早越省钱。等到出了线上事故再补日志，你会发现自己已经失去了最宝贵的现场证据。
排第二的是 Prompt 版本管理。Agent 的 Prompt 不是写一次就完的，它跟代码一样需要版本管理。我用 Git 专门维护一套 Prompt 仓库，每次改动都要拉分支、跑测试、合并发布。这样可以快速回滚不稳定的 Prompt 变更。
排第三的是模型降级链。一套生产 Agent 不能只绑定一个模型。我在 Harness 层做了模型间的故障转移：主要模型超时或报错时，自动切换到备用模型继续推理；如果备用模型也异常，再降级为规则回复。这也是我在线上稳定运行超过半年没有出现大规模故障的关键机制。
7.3 团队协作中的约定与规范
最后聊几句管理向的经验。Agent 项目最怕“每个人都在随意改 Prompt、随意加工具”。我坚持在团队里立几条铁规矩：任何工具变更必须更新工具文档；任何 Prompt 变更必须附测试记录；任何模型参数调整必须走配置变更流程而不是写死在代码里；Agent 行为变更上线前必须跑回归集。
这些规矩听着像是增加负担，但真正做到之后，项目的维护成本会明显下降。Agent 工程跟传统软件开发不一样的地方在于：它的“代码”一部分是由不可控模型生成的，所以工程侧的纪律、规范、控制措施比单纯写代码重要得多。也正因如此，Harness、Loop、Graph 这一套三层架构，才不只是技术偏好，而是一种工程理念：让 Agent 的能力发挥上限，同时让它的行为守住底线。
