1. 从三个词说起为什么 Agent 工程需要分层思考第一次听到“Harness、Loop、Graph”这三个词被放在一起讨论是在一个做智能体落地的技术群里。当时有人问“为什么我照着教程搭的 Agent跑单轮任务挺像样一上多步骤就崩”底下有个老哥回了一句“因为你只写了 Loop没搭 Harness更没设计 Graph。”这句话当时没完全听懂后来越做越深才发现这三个词其实对应着 Agent 工程从“能跑”到“跑得稳”再到“跑得复杂”的三个层次。先把话说直白一点。Harness是智能体的“骨架和缰绳”负责把模型、工具、记忆、权限这些东西组装成一个可运行、可控制、可观测的整体Loop是智能体的“心跳和节奏”决定它怎么一轮一轮地思考、行动、观察、再思考Graph是智能体的“路线图和协作网”用来描述多个步骤、多个角色、多个分支之间怎么流转和配合。三者不是替代关系而是层层叠加的关系。你可以只写一个 Loop 就跑起来一个简单 Agent但一旦要上生产、要接真实业务、要处理异常和并发Harness 和 Graph 就绕不开了。这篇内容适合谁看如果你已经用大模型 API 做过一些自动化脚本或者用现成框架搭过 demo但总觉得“能演示不能上线”那这篇就是写给你的。如果你是完全的新手也没关系我会尽量用生活化的类比把每个概念讲透再补上可以直接参考的代码结构和参数思路。核心关键词 Harness、Agent、Loop、Graph、架构会贯穿全文但我不会为了堆词而堆词每个词出现的地方都会对应一个真实要解决的问题。我自己的经验是很多人做 Agent 失败不是因为模型不够强而是因为把三个层次混在一起写。一个文件里既有工具注册又有循环控制还有多角色调度最后调试的时候根本不知道问题出在哪一层。把这三层拆开分别设计、分别测试、分别观测是 Agent 工程化最实用的一条路径。下面我就按这个思路一层一层拆给你看。2. Harness 层Agent 的骨架、缰绳与仪表盘2.1 Harness 到底解决什么问题Harness 这个词原意是“马具、挽具”套在马身上用来控制方向和力度。放到 Agent 工程里它指的是把模型能力约束和组装成可控系统的这一层。模型本身是一个概率性的文本生成器它不知道什么是工具、什么是权限、什么是超时、什么是重试。Harness 的职责就是把这些工程要素包在模型外面让它变成一个“能安全干活”的智能体。具体来说一个完整的 Harness 通常要管这几件事工具注册与调用模型说要用某个工具Harness 负责真正执行并把结果喂回去、上下文管理哪些历史要保留、哪些要压缩、哪些要丢弃、权限与安全哪些操作允许、哪些要人工确认、哪些直接拒绝、可观测性日志、追踪、耗时、token 消耗、错误处理工具失败怎么办、模型输出格式不对怎么办。你可以把 Harness 理解成 Agent 的“操作系统内核”Loop 和 Graph 都是跑在它上面的应用逻辑。为什么不能把这些直接写在 Loop 里因为一旦写在一起你的循环代码会迅速膨胀成几百行的意大利面条。工具注册改一次循环逻辑要跟着动权限策略调整一次又得回头改循环。Harness 单独抽出来之后Loop 只需要关心“下一步该干什么”工具怎么执行、权限怎么校验、日志怎么打全部交给 Harness。这就是关注点分离在 Agent 工程里的具体落地。2.2 Harness 的核心模块拆解我习惯把 Harness 拆成五个模块来设计每个模块职责单一方便单独测试和替换。第一个是模型适配层。不同厂商的模型 API 在参数命名、消息格式、工具调用协议上都有差异。适配层的作用是把上层统一的调用接口翻译成具体厂商的格式。比如上层说“给我一个带工具调用的回复”适配层负责把它转成对应 API 的请求体再把返回结果转回统一格式。这样做的好处是换模型的时候只改适配层Loop 和 Graph 完全不用动。第二个是工具注册表。每个工具需要声明名称、描述、参数 schema、执行函数、超时时间、是否需要确认。描述和 schema 会作为提示词的一部分发给模型所以写得清楚不清楚直接决定模型会不会正确调用。我踩过的坑是工具描述写得太简略模型经常传错参数后来把每个参数的示例值都写进描述里调用准确率明显上升。第三个是上下文管理器。Agent 跑多轮之后历史消息会越来越长token 消耗和延迟都会飙升。上下文管理器要决定保留策略最近 N 轮全保留更早的做摘要工具返回的大段内容做截断或压缩。这里有个经验是工具返回结果如果超过一定长度不要原样塞回上下文而是先做结构化提取只把关键字段喂回去。第四个是权限与安全网关。不是所有工具调用都应该无条件执行。删除文件、发送消息、调用付费接口这类操作需要设置确认机制或白名单。安全网关在工具执行前拦截根据策略决定放行、拒绝还是转人工确认。这一层在 demo 阶段经常被忽略但一上生产就是刚需。第五个是可观测性模块。每次模型调用、每次工具执行、每次循环迭代都要打上结构化日志记录耗时、token 数、输入输出摘要、错误信息。没有这一层线上出问题你只能靠猜。我一般会用 trace id 把一次完整任务的所有调用串起来排查问题时能一眼看到是哪一步卡住了。2.3 Harness 设计的三个关键取舍设计 Harness 的时候有几个取舍点值得单独说。取舍一工具执行是同步还是异步。同步实现简单但一个慢工具会阻塞整个循环。异步能提升吞吐但错误处理和顺序保证会复杂很多。我的建议是如果工具大多是毫秒级的本地操作同步就够了如果涉及网络请求或耗时计算至少要把工具执行做成可超时、可取消的避免一个卡死的工具拖垮整个 Agent。取舍二上下文是全部保留还是动态裁剪。全部保留实现最简单但成本和延迟会随轮次线性增长。动态裁剪需要设计策略但能显著降低成本。我通常的做法是设置一个 token 预算超过预算就触发摘要或截断摘要用一个小模型来做成本可控。取舍三权限校验放在 Harness 还是工具内部。放在 Harness 的好处是统一策略、集中管理放在工具内部的好处是工具可以自己决定细粒度权限。我倾向于两层都做Harness 做粗粒度白名单工具内部做细粒度校验。这样即使 Harness 策略配置有误工具内部还有一道防线。提示Harness 的每个模块都应该能单独用 mock 替换这样你可以在不调用真实模型的情况下测试工具执行、权限校验、日志记录等逻辑大幅提升开发效率。3. Loop 层Agent 的心跳、节奏与终止条件3.1 Loop 的本质一个带状态的决策循环Loop 是 Agent 最核心的运行逻辑。剥开所有包装它就是一个循环观察当前状态决定下一步动作执行动作更新状态判断是否结束。这个循环听起来简单但每个环节都有大量细节决定成败。观察当前状态指的是把上下文、工具返回结果、外部输入整合成模型能理解的输入。决定下一步动作是让模型输出一个结构化的决策可能是调用某个工具可能是给出最终答案也可能是请求人工介入。执行动作由 Harness 完成。更新状态包括把工具结果写回上下文、更新轮次计数、记录日志。判断是否结束则要看是否达到终止条件。为什么叫 Loop 而不是“流程”因为 Agent 的路径不是预先固定的而是每轮根据模型输出动态决定的。这既是它的强大之处也是它难以控制的原因。一个设计不好的 Loop可能陷入无限循环可能提前终止可能反复调用同一个工具。所以 Loop 设计的核心其实是终止条件和状态管理。3.2 终止条件的五种常见设计终止条件是 Loop 里最容易被低估的部分。我见过太多 Agent 因为终止条件没设计好要么跑飞了烧掉大量 token要么该继续的时候提前停了。常见的终止条件有这么几种。第一种是模型主动给出最终答案。模型输出中不包含工具调用而是直接给出回答循环结束。这是最自然的终止方式但依赖模型判断准确。有些模型会在信息不足时也强行给答案这时候需要配合其他条件。第二种是达到最大轮次。设置一个硬上限比如 10 轮或 20 轮超过就强制结束并返回当前结果。这是兜底机制防止无限循环。上限设多少要看任务复杂度简单问答 3 到 5 轮够了复杂任务可能需要 15 到 20 轮。第三种是达到 token 或时间预算。累计 token 消耗或总耗时超过阈值就终止。这在成本敏感的场景很重要。我一般会同时设置轮次和 token 两个上限哪个先到就停。第四种是检测到重复动作。如果连续几轮调用同一个工具、传同样的参数说明模型卡住了应该终止或触发纠错。实现方式可以是对最近几轮的动作做哈希发现重复就干预。第五种是外部信号终止。比如用户主动取消、上游系统超时、人工审核拒绝。这要求 Loop 支持从外部中断并且中断时能优雅地保存状态。实际生产中这几种条件通常是组合使用的。我的默认配置是模型给出最终答案则正常结束达到最大轮次则强制结束并标记为“未完成”检测到重复动作则终止并返回错误token 超预算则终止并记录。这样既给了模型发挥空间又有足够的兜底。3.3 状态管理与上下文膨胀的对抗Loop 每跑一轮上下文就会增长。如果不加控制几轮之后 token 消耗就会失控。对抗上下文膨胀我有几个实用手段。手段一工具结果结构化压缩。工具返回的原始数据往往包含大量冗余字段不要原样塞回上下文。比如一个搜索工具返回 20 条结果每条有 10 个字段你只需要标题、摘要和链接那就只提取这三个字段。这一步能省下大量 token。手段二历史消息滚动摘要。保留最近几轮的完整消息更早的消息用一个小模型做摘要摘要控制在几百 token 以内。摘要要保留关键决策和事实丢弃过程性细节。手段三状态外置。把一些结构化状态比如已收集的字段、已完成的步骤存在 Loop 外部的状态对象里而不是全放在对话历史中。每轮只把必要的状态注入提示词。这样上下文长度不会随轮次无限增长。手段四分阶段重置。对于长任务可以把它拆成几个阶段每个阶段结束后重置上下文只把阶段产出传递给下一阶段。这相当于用 Graph 的思路来管理 Loop 的上下文。注意上下文压缩是有信息损失的压缩策略太激进会导致模型丢失关键信息表现下降。建议在压缩前后做对比测试确认关键任务的成功率没有明显下降。3.4 Loop 的调试与观测要点Loop 出问题的时候最难的是定位是哪一轮、哪个决策出了错。我的做法是给每一轮都打上详细日志轮次编号、模型输入摘要、模型输出原文、决策类型、工具调用参数、工具返回摘要、耗时、token 消耗。这些日志按 trace id 串起来排查时能完整回放一次任务的执行过程。另外我会在开发阶段加一个“单步模式”让 Loop 每执行一轮就暂停人工确认后再继续。这在调试复杂任务时非常有用能直观看到模型每一步的决策是否符合预期。上线前再关掉单步模式切成全自动。还有一个经验是把 Loop 的每一轮决策都当成一个独立的分类问题来评估。也就是说给定当前状态模型应该选择哪个动作如果发现某类状态下模型经常选错就可以针对性地优化提示词或补充示例。这种细粒度的评估比只看最终任务成功率更能定位问题。4. Graph 层多步骤、多角色、多分支的协作网4.1 什么时候需要从 Loop 升级到 Graph单 Loop 能处理的任务是那种“一条路走到黑”的线性任务。但真实业务里很多任务是有分支、有并行、有角色分工的。比如一个客服 Agent要先分类用户意图再根据意图走不同的处理流程有些流程还需要多个角色协作。这种时候单 Loop 就会变得非常臃肿提示词里塞满了各种分支逻辑模型很容易混乱。Graph 的思路是把任务拆成节点和边。每个节点是一个相对独立的处理单元可以是一个 Loop、一次模型调用、一个工具执行或者一段确定性代码。边定义了节点之间的流转条件。这样整个任务就变成了一张有向图执行引擎按照图的定义来调度节点。从 Loop 到 Graph 的升级本质是从“一个大脑做所有决策”变成“多个专门单元各司其职由编排层协调”。这带来的好处是每个节点可以单独优化、单独测试、单独替换整体复杂度被分解了。4.2 Graph 的节点类型与边设计节点类型可以粗分为几类。模型节点负责需要语言理解和生成的环节比如意图分类、内容生成、信息抽取。工具节点负责确定性操作比如查数据库、调接口、发消息。条件节点负责根据状态做分支判断可以是规则判断也可以是模型判断。人工节点负责需要人工介入的环节比如审核、确认、补充信息。子图节点负责把一组相关节点封装成一个可复用的子流程。边的设计决定了图的灵活性。顺序边表示 A 完成后走 B。条件边表示根据某个条件决定走 B 还是 C。并行边表示 A 完成后同时触发 B 和 C等两者都完成再汇合。循环边表示某个节点可以回到之前的节点形成子循环。设计图的时候要特别注意避免出现无法到达终点的环以及并行分支的汇合条件要明确。我一般会先用纸笔把任务的流程图画出