做 Agent 工程这两年我最大的感受是跑通一个 Demo 很容易写一个能在生产环境扛住真实流量的 Agent 很难。难在Agent这三个字母背后藏着一堆没人替你分担的工程问题——工具怎么接、权限怎么控、循环怎么停、流程怎么排、出错了怎么查。拆来拆去我发现所有问题都能归到三层Harness、Loop、Graph。这篇文章就围绕三层架构展开讲清楚每一层解决什么问题、生产里怎么落地、有哪些文档里不会写的坑。适合已经玩过 LangChain、跑过几个 Agent Demo、现在想往生产级架构走的朋友。1. 三层架构的整体设计与思路拆解1.1 不分层的 Agent 为什么会死在生产环境先说一个我早期踩过的大坑。那时我写了个全能助手Agent把搜索、数据库查询、文件读写、发邮件、调用内部 API 一共三十多个工具一股脑全塞进系统提示词里让大模型自己选。Demo 阶段很惊艳什么都能干。一上生产就崩模型经常选错工具、参数格式五花八门、跑着跑着陷入同一个报错的死循环最关键的是没人敢给它放开文件删除和数据库写操作的权限——因为根本没有权限控制这层东西。这个经历让我意识到Agent 不是一个大模型加一堆工具它其实是一个工程系统必须分层。Harness 负责把能力装进壳里Loop 负责让思考循环运转Graph 负责把流程编排成可预测的路径。哪一层缺失整个系统都会在某个意想不到的时刻出问题。1.2 三层各自的职责与边界先给一张我常用的对照表把三层分开看层级核心职责典型实现方式生活化类比Harness能力接入、权限控制、上下文装配、安全边界工具注册中心、MCP、插件系统、沙箱身体和感官Loop推理迭代、行动执行、结果反馈ReAct 循环、Plan-and-Execute、反思循环大脑回路Graph流程定义、状态流转、分支与人工审批状态机、LangGraph、可视化编排器骨架和剧本这三层不是三个独立组件而是同一个 Agent 运行时的三个剖面。Harness 在最底层提供能力Loop 在中间驱动决策Graph 在最上层编排路径。打个比方Graph 是剧本告诉 Agent先调研再写方案写完要人工确认才能发送Loop 是演员的临场发挥在剧本允许的范围内不断思考、尝试、根据反馈调整Harness 是舞台和道具组保证演员能安全地用上所有道具且不能越界。2. Harness 层实战把工具、权限和上下文装进一个安全的壳2.1 Harness 到底在管什么Harness 直译是马具——套在牲口身上用来连接工具的那套装备。放到 Agent 工程里Harness 就是那个把大模型和外部世界连接起来的装备层。它管三件事能力暴露、权限边界、上下文装配。能力暴露指的是 Agent 能用哪些工具。核心问题是工具不是越多越好。我做过实验在系统提示词里塞 10 个工具时模型工具调用准确率在 95% 以上塞到 30 个准确率掉到 70% 左右超过 50 个模型开始频繁在无关工具之间纠结响应时间也跟着涨。所以生产级 Harness 一定要做工具分组和按需加载——不是所有工具都常驻提示词而是根据当前任务动态挂载。权限边界是 Harness 最容易被忽略、但生产环境最致命的部分。我在给客户做企业内部 Agent 时第一条铁律就是任何有副作用的操作删数据、改配置、发消息、下单必须经过权限校验。Harness 里做一个工具代理层统一拦截所有工具调用按只读、受限写、高危操作分三档权限高危操作不开放给模型自动调用只允许人工触发。上下文装配则是把系统提示词、工具描述、对话历史、检索到的知识片段拼装成模型能高效消费的输入。这一步看着简单实际坑很多。比如工具描述太长会挤占模型的注意力预算我一般要求每个工具描述控制在 100 字以内参数名用能自解释的命名枚举值写清楚模型选错参数的概率会低非常多。2.2 工具注册体系与插件生态工具注册是 Harness 的神经接口。现在主流的做法是统一走函数调用协议——把工具的 JSON Schema、输入输出定义清楚模型按 Schema 生成调用参数Harness 负责执行并返回结果。更现代一点的做法是走 MCP 这类标准化协议让工具以服务的形式挂载Agent 启动时自动发现能力清单。这里要特别提一下插件生态。最近 DeepSeek Harness、Claude Agent Skills 这类项目火起来本质上都是在 Harness 层做文章——通过安装插件或技能来扩展 Agent 的能力。比如 DeepSeek Harness 的插件机制允许你把一套写好的工具描述、调用逻辑、甚至附带的知识文件打包成一个 Skill部署到 Agent 运行时里。我实际部署过一次带技能的 Harness 到公司内网服务器流程大概是写好 Skill 目录结构技能描述、工具实现、参考文档通过 Harness 的插件加载接口挂载然后重启运行时让插件生效。整个过程不用改核心代码这种可插拔性在生产里太重要了特别是当你需要给不同业务团队挂载不同技能集的时候。提示插件加载失败在生产环境里非常常见。有一次我遇到 Harness 启动时报插件加载失败排查半天发现是插件目录里一个描述文件的格式不符合校验规范。这类问题建议在 Harness 里加一个插件自检命令启动时逐项校验每个插件的描述、入口、依赖并输出清晰的错误日志不然排起来真的很费时间。2.3 Harness 与 Agent 框架到底有什么区别很多朋友搞不清 Harness 和 Agent 框架比如 LangChain、LangGraph的区别。我自己的理解是框架解决的是Agent 的逻辑怎么组织Harness 解决的是Agent 的能力怎么安全地暴露和使用。框架管循环、管编排Harness 管工具接入、管权限、管上下文、管插件生命周期。两者是配合关系不是替代关系。你可以用 LangGraph 做流程编排同时在每个节点上挂一个 Harness 来处理工具调用层的事情。举个最直观的例子我在生产里常把 Harness 设计成独立服务暴露执行工具调用这个接口给上层 Loop 和 Graph 调用。所有工具的出入参、权限校验、调用审计都集中在这一层。上层完全不关心工具怎么注册、权限怎么验只需要拿着工具名和参数来调用就行。这样 Graph 层换流程、Loop 层改策略工具层完全不受影响这是分层带来的最大红利。3. Loop 层实战让模型想一步、走一步、看一步3.1 ReAct 循环的底层逻辑Loop 是 Agent 的思考引擎。当前绝大多数生产级 Agent 跑的还是 ReAct 模式Thought思考→ Action行动→ Observation观察。模型先根据当前状态决定下一步做什么调一个工具拿到结果再基于结果继续思考。这个循环不断重复直到任务完成或者触发终止条件。看着简单但生产环境里最难的就是给这个循环定终止条件。模型天然有不撞南墙不回头的倾向同一个报错反复尝试、同一个工具反复调用、答题答不出来就开始绕圈。我见过最夸张的一次一个 Agent 因为 API 超时在十分钟里重试了四十多次同一个请求Token 费用烧掉不少任务还没完成。所以我在做 Loop 层的时候一定会加三样东西最大迭代次数上限、单轮工具的失败重试上限、以及一个循环停滞检测——如果连续三轮观察结果没有带来任何新信息比如错误信息一模一样就直接终止循环并转入人工兜底。这三样缺一不可它们决定了 Agent 是可控的自动执行还是失控的自动烧钱。3.2 从单步循环升级到 Plan-and-Execute单步 ReAct 的问题是缺少全局规划。比如一个任务是调研三个竞品并生成对比报告模型如果一步步来经常做到一半忘记最初目标或者在某一个竞品上花费过多精力。Plan-and-Execute 的思路是在进入执行循环前先让模型基于任务生成一个多步骤计划然后每一步执行时验证是否按计划推进最后全部执行完再做总结。我实际跑下来的感受是Plan-and-Execute 在任务复杂度高、步骤明确的场景下效果很好但有个坑模型生成的计划可能本身有问题。所以生产里我会在 Graph 层给计划加一个人工或规则校验节点计划不合理就退回重新生成而不是直接执行。另外计划也不宜太细步骤超过十步时模型自己都容易被计划文档绕晕建议粗粒度计划加细粒度执行。还有一种常见的 Loop 变体是反思循环。在执行完一轮后让模型自己分析刚才哪里做得不够好下次应该怎么调整这种 Self-Reflection 模式在代码生成、文档写作这类开放式任务上提升很明显但会显著增加 Token 消耗和延迟要谨慎使用一般只在关键节点启用。3.3 记忆与状态Loop 的短期工作台和长期档案库Loop 层还有一个容易被低估的模块记忆。Agent 的上下文窗口是有限的但任务往往多轮、长时长。我的做法是把记忆分成两层短期记忆就是当前 Loop 的对话历史和观察结果放在上下文里长期记忆存在外部存储里包括用户偏好、历史任务结论、领域知识片段需要时通过检索放回上下文。这里有个血泪教训短期记忆如果不做裁剪上下文会越滚越长既费 Token 又让模型迷失在长文本里。我一般设一个滑动窗口保留最近 N 轮的关键信息更早的内容摘要成一段缓存文本放在最前面。裁剪策略直接影响任务质量剪得太狠丢失关键上下文剪得太松浪费 Token这个 N 值需要根据你实际任务的上下文依赖度来调没有银弹。4. Graph 层实战从线性流程升级为可干预的状态机4.1 Graph 解决的是流程可控性问题如果说 Loop 是自由发挥的大脑那 Graph 就是约束发挥的剧本。纯 Loop 的问题是不可预测同一个任务这次跑三条路径下次跑五条路径输出质量完全看模型当天状态。Graph 层把任务流程显式地定义成节点和边的集合每个节点做一件事边决定流转条件。这里推荐用状态机的思维来理解 Graph整个任务流程就是一个状态集合每个节点代表一个状态节点之间的边代表状态转移条件和动作。比如一个内容审核Agent可以定义成接收投稿节点A→ 自动初筛节点B→ 命中规则则转人工节点C未命中则自动通过节点D→ 通过后推送节点E。这些节点和流转条件都是提前定义好的模型的自由发挥被约束在每个节点内部怎么执行这个范围内。4.2 条件分支、人工确认与超时兜底Graph 层最常用的三个能力是条件分支、人工确认和超时兜底。条件分支让流程可以看情况走不同路径比如根据用户意图分类决定走问答路径还是任务执行路径。人工确认节点让高风险操作必须有人拍板比如生成合同 → 法务确认 → 才能发送给客户。超时兜底则是给每个节点设一个最大执行时间超时就走降级路径。在实际落地时我特别强调节点要有幂等性设计。所谓幂等就是一个节点重复执行多次结果和执行一次一样。因为生产环境里节点执行可能失败、可能超时重试如果节点不幂等比如发邮件执行两次就发了两封重试机制反而会放大问题。我的做法是有副作用的节点在执行前先查一下执行记录如果这个任务在这个节点已经成功执行过就跳过直接返回。4.3 多 Agent 协作编排主从模式与流水线模式Graph 层的进阶玩法是多 Agent 编排。我常用的两种模式主从监督模式和流水线模式。主从模式里有一个监督者Agent 负责接收任务、拆分给多个专家Agent、收集结果并汇总流水线模式则是把任务拆成有序阶段每个阶段由不同 Agent 完成前一个的输出是后一个的输入。主从模式适合开放性任务比如做一个市场分析报告可以拆给数据收集 Agent行业研究 Agent文案撰写 Agent并行干最后监督者汇总。流水线模式适合流程固定的任务比如代码开发流水线需求分析 Agent → 代码生成 Agent → 测试 Agent → 代码审查 Agent。两种模式各有优劣主从模式灵活但监督者容易成为瓶颈流水线模式稳定但流程僵化得按场景选。工具方面LangGraph 这类库把 Graph 层的状态流转做得很成熟适合代码型团队。可视化一点的可以试试 Snap Graph Builder 这类图形化编排工具拖拽节点、连线配条件对非程序员友好很多。我个人的建议是小团队、流程简单的先别上框架手写状态机反而更可控流程复杂、节点多的再上框架省掉大量状态管理代码。5. 三层协同一个完整的企业知识问答与任务执行案例5.1 场景与总体设计说个我实际交付过的案例帮大家把三层串起来。场景是给一家企业做内部智能助手两类核心需求一是知识问答从企业知识库里检索资料回答员工问题二是任务执行比如帮员工创建工单、预约会议室、提交审批。这两类需求看起来简单但生产里牵扯到权限、多轮交互、人工审批不拆三层根本做不稳。层级本案例的做法Harness挂载检索工具、工单系统 API、会议室系统 API划分只读/受限写/高危三档权限LoopReAct 循环 最大 8 轮迭代问答场景浅循环任务场景深循环 反思Graph意图识别 → 问答分支 / 任务分支 → 参数确认 → 人工审批 → 执行 → 反馈5.2 每层的具体配置细节Harness 层我把知识库检索封装成一个只读工具工单创建封装成受限写工具会议室释放这类操作直接设为高危只能由管理员手动触发。工具调用统一走审计日志谁在什么时间调了什么工具、传了什么参数全部留痕。这个设计救过我一次——后来有员工反馈莫名多了一封会议通知一查审计日志是会话历史里残留的上下文让模型误以为是用户在预约自动调了会议室工具。查清原因后我在 Harness 层加了意图二次确认拦截敏感操作执行前必须回显参数让用户确认。Loop 层我做了一个动态迭代上限知识问答任务最多 5 轮因为检索类问题通常两三轮就能解决给多了纯浪费任务执行类最多 12 轮因为中间可能要填参数、查状态、处理异常。反思节点只在任务执行失败后开启让模型先总结失败原因再重试实测这一步能把任务成功率提升二十个百分点左右但代价是每次失败重试要多花一轮 Token所以只在关键路径上开。Graph 层我把整个流程定义成了八个节点意图识别、意图确认、知识检索、答案生成、参数收集、审批提交、执行操作、结果反馈。意图识别节点如果置信度低会进入意图确认节点反问用户涉及高危操作会进审批提交节点走人工确认后再执行。整个流程在状态机里是显式的任何一步出了问题、卡在哪个节点打开状态图一目了然。5.3 调用链与数据流转一次典型的任务执行请求完整调用链是这样的用户消息进入 Graph 的意图识别节点由 Loop 层的模型做一次分类结果指向任务分支状态流入参数收集节点Loop 层通过多轮对话把会议室时间、参会人等参数补齐补齐后流入审批提交节点Graph 暂停流程生成一个审批链接发给管理员管理员确认后状态机继续流转调用 Harness 层的会议室预订工具执行执行结果回到 Loop 层汇总成自然语言反馈给用户。这个案例跑了大半年最稳定的数据是三层的解耦带来的Harness 层换过一次会议室系统的 API只改了工具实现Loop 和 Graph 完全没动Graph 层调整过审批流程的顺序也只动了状态机定义。如果当初不分层任何一层的变化都可能引发连锁故障这是我坚持三层架构最实在的理由。6. 常见问题与排查技巧实录6.1 高频故障速查表故障现象大概率原因排查思路Agent 反复调用同一个失败工具Loop 层缺少失败重试上限检查最大迭代数和单工具重试限制加循环停滞检测模型频繁选错工具Harness 层工具数量过多或描述不清晰精简工具组、按任务动态挂载、缩短工具描述跑着跑着上下文越滚越大Loop 层短期记忆没做裁剪加滑动窗口策略历史内容摘要化流程卡在某个节点不前进Graph 层缺少超时兜底每个节点设超时超时走降级路径插件加载失败、功能不生效Harness 层插件校验或依赖问题加启动自检检查插件描述格式和依赖版本相同任务不同结果、质量波动大Loop 层没有规划或反思机制引入 Plan-and-Execute 或关键节点反思循环人工审批后流程不继续Graph 层状态恢复逻辑缺失审批回调要能正确恢复挂起节点的上下文6.2 两个最值的调试手段调试 Agent 生产问题我最依赖两样东西完整的调用链追踪和可回放的执行日志。调用链追踪就是把每一次工具调用、每一轮 Loop 的思考内容、每一条 Graph 状态转移都打上 trace_id 串起来。出问题的时候按 trace_id 一查就能看到 Agent 在哪个节点、哪一轮循环、哪次工具调用上出的岔子。这个成本不高但价值极大建议从第一天就做别等项目复杂了再补。另一个是可回放日志。我把每轮 Loop 的输入输出完整落盘注意脱敏出问题时可以把这一段历史重新喂给模型看它在同样的上下文下会不会再次犯同样的错误。这个手段在排查那种偶发性问题特别好用——不是每次必现、但隔三差五出一次的 bug靠回放日志能把概率问题变成确定问题。6.3 三层调优的先后顺序如果让我给一个调优的优先级顺序是先保证 Harness 层不出安全性问题再保证 Graph 层流程可控最后才是优化 Loop 层的效果。理由是Harness 出错是事故级的乱删数据、乱发消息Graph 出错是体验级的任务卡死、流程乱跳Loop 出错只是质量级的结果不够好。很多团队一上来就死磕提示词、调模型效果结果最基本的权限和流程都没管好这是本末倒置。7. 最后分享几点实操体会做多了 Agent 项目我对三层架构最深的体会就是分层不是为了架构好看是为了让系统能活过三个月。第一个月大家都在新鲜感里后面就是无穷无尽的工具变更、流程调整、效果优化。没有清晰的分层每一次变更都是一次冒险有了分层绝大多数变更都变成了局部修改。另外一个体会是别过度设计。我见过有人为了演示三层架构把一个查天气的机器人也硬套上 Graph 编排和插件系统结果复杂度远超收益。我的原则是任务只有一个工具调用直接用 Loop 就够了任务有明确的多步骤流程才值得引入 Graph工具多、权限敏感才需要认真做 Harness。架构是为问题服务的不是反过来。最后分享一个小技巧给每层都准备一个降级开关。Harness 挂了可以退回只读模式Loop 出问题可以退化成单轮问答Graph 故障可以取消人工审批节点直接转人工客服。这三个开关在关键时刻能救命——生产事故发生时能快速降级比能快速修复更重要。