这两年 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 的所有能力都跑在这个“底座”上。没有 HarnessAgent 就是裸奔的模型调用有了 Harness模型才有一个稳定的环境去感知工具、调用能力、记录行为。Loop 则是 Agent 的运行循环。模型不是一次性输出答案就完事的它往往需要“思考 → 调用工具 → 观察结果 → 再思考”这样的多轮迭代。这个反复执行的过程就是 Loop。很多生产事故恰恰出在这里——循环没有超时控制、没有最大迭代次数、没有异常恢复机制结果 Agent 在同一个错误工具调用上反复打转白白消耗 Token 直到预算烧光。Graph 是把 Agent 的决策过程从“自由发挥”变成“有路径可循”的编排层。你可以把 Agent 的任务拆成多个节点比如“意图识别 → 信息收集 → 计划生成 → 工具执行 → 结果验证”每个节点之间用边连接形成一张有向图。Graph 的意义在于不是每一步都让模型自由决策而是让模型在允许的路径范围内选择这样既保留了大模型的灵活性又把不可控性关进了笼子里。1.2 为什么三层缺一不可很多 Agent 框架比如 LangChain、LlamaIndex其实都内置了这三层结构只是它们把它们包装成了不同的接口。我见过一些团队只用了“模型 Prompt”就开始做 Agent结果项目到后期维护成本极高因为所有逻辑都揉在 Prompt 里出问题根本无从排查。打个比方Harness 是房子的地基和管线Loop 是房间里的暖气系统持续供热Graph 是房间之间的走廊和门决定你怎么从一间屋走到另一间屋。没有地基房子塌没有暖气人冻死没有走廊房间之间无法连通。生产环境里的 Agent 也一样没有 Harness工具调用混乱、上下文溢出、安全问题频发没有 LoopAgent 只能做单轮决策无法处理需要多步操作的任务没有 GraphAgent 决策路径完全由模型自由发挥既不可预测也不可审计。从另外一面看这三层也是从“最简单可用的 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 IDLoop 的所有状态都挂在 Session 内部。4. Graph 层深度解析Agent 的路径规划与编排策略4.1 Graph 层的角色从“自由发挥”到“有限路径”Graph 层是三层架构里最像“架构”的部分因为它让 Agent 的决策路径变得可设计、可控制、可审计。没有 Graph 时Agent 在一轮 Loop 里可以任意选择工具、任意切换意图路径不可预期有了 GraphAgent 只能在预设的“节点”之间转移每个节点执行一个明确定义的子任务。我举一个实际项目的例子做一个会议纪要 Agent接收到一段录音转文字后要输出会议纪要和待办事项。如果只用 LoopAgent 会自由地决定怎么处理这段文字可能出现“先摘要、再提取待办、但摘要质量差、然后重新摘要”这类混乱路径。用 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. 三层架构的组合实战从零搭建一个生产级 Agent5.1 选型自研还是用框架经常有人问我搞这套三层架构到底应该自己写还是用现成框架我的回答是框架可以用但不能全依赖。比如你用 LangGraph它本身就把 Graph 和 Loop 都封装好了但 Harness 层仍然需要自己搭你用 CrewAI 能快速搭建多 Agent 协作但一旦涉及复杂的业务安全策略还是得自己写扩展。我目前的偏好是“轻框架 核心自研”集成层用 LangGraph 做 Graph 的骨架工具管理和上下文管理完全自研模型层用统一 Provider 接口。这样做的好处是既有框架帮你处理图的状态流转和持久化又能保证 Harness 层的业务逻辑完全可控。如果你对 LangGraph 不熟直接用 Python 或者 TypeScript 手写一个简单的 DAG 引擎也不难核心也就一百多行代码。模型选型上也说两句。目前我用得比较多的是 DeepSeek 和 ClaudeDeepSeek 性价比高适合中长文本处理、批量任务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 层每多一轮都要多花 TokenHarness 层的日志和状态管理也会消耗计算资源。所以生产环境里需要一组合适的“降本增效”策略。延迟优化上我的做法有几种一是把硬路由能解决的问题全部用规则做完避免软路由反复调用模型二是给模型配置较低的推理温度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 的能力发挥上限同时让它的行为守住底线。