做 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；划分只读/受限写/高危三档权限 |
| Loop | ReAct 循环 + 最大 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 故障可以取消人工审批节点直接转人工客服。这三个开关在关键时刻能救命——生产事故发生时，能快速降级比能快速修复更重要。
