你的 agent 在演示时惊艳全场，一接真实文件、API、浏览器和客户数据就原形毕露。它一遍遍回复“已完成”，交付物却过不了验收；任务稍微复杂一点，它就陷入循环、烧掉预算、交出没人敢用的结果。

 

你开始怀疑是不是模型不行。换更强的模型，症状依旧。

因为问题根本不在模型。当 agent 越过玩具 demo、开始碰文件、API、文档、客户和生产代码时，你早就不只是在“提示一个模型”了，你是在设计一套系统。而在这套系统里，有三个概念被反复混在一起：harness（环境）、loop（循环）、graph（流程图）。它们都围着同一个模型转，都会影响可靠性，但解决的是完全不同的问题。混着用，你就是在错误的一层上修 bug。

 

01 一句话建立三层心智模型：环境 → 反馈 → 流程

 

先给你能记住的版本，也是这篇长文的核心结论：

• •Harness engineering（环境工程）负责把模型周围的环境搭好；
• •Loop engineering（循环工程）负责设计“干活-反馈”的重复循环；
• •Graph engineering（图工程）负责把工作流的拓扑显式画出来。

记忆模型就三个词：环境 → 反馈 → 流程。

环境（harness）给模型工具、记忆、控制和工作区；循环（loop）决定工作怎么被重试、检查和改进；图（graph）定义下一步到底允许发生什么。

为什么这三件事必须分开？因为一个裸模型什么真实工作都做不了。它不能跨会话维持项目状态，不能安全调用工具，不能检查浏览器，不能执行权限，不能重试失败的任务，不能验证输出质量，不能把任务路由给不同专家，更不知道什么时候该停。这些能力全部来自模型周围的那套系统。

所以当 agent 软件走向成熟，一套实用的分层栈正在成型：harness 给模型工作条件，loop 让工作可重复可验证，graph 让复杂流程显式可控。一旦你用这三层去看，很多 AI 架构上的混乱会自动消失。

 

02 第一层 Harness：环境决定模型“能不能操作”

 

先看最容易被忽略、又最决定成败的一层。

一个严肃的 harness 通常包含六件事：

1. 上下文注入——模型动手前能看到什么。指令、检索到的知识、对话状态、记忆、策略、任务规则。

2. 动作面——模型能做什么。API 调用、浏览器操作、shell 命令、代码执行、MCP 工具、数据库、自定义函数。这里的 MCP（Model Context Protocol）现在已经是把 AI 应用接到外部系统的开放标准，官方文档把它比作 AI 应用的 USB-C 口：数据源、工具、工作流都通过它统一接入，Claude、ChatGPT、VS Code Copilot、Cursor 都在支持。

3. 持久化——什么东西能跨时间存活。文件、检查点、会话状态、进度日志、git 历史、长期记忆。

4. 执行控制——这次运行怎么被管理。重试、超时、预算、模型选择、子 agent 生成、审批闸门。

5. 安全与治理——什么保证系统安全。最小权限、隔离、白名单、密钥处理、人工审批。

6. 可观测性——出了问题怎么查。trace、工具输入输出、状态转移、延迟、成本、评估结果。

为什么这层这么重要？两个团队用同一个模型，结果可以天差地别。一个团队给模型干净的工具、稳定的状态、结构化的记忆、清晰的权限、可观测的执行；另一个团队只给一个含糊的 prompt、一堆乱糟糟的工具、充满噪声的上下文、没有记忆、没有验证。模型可能完全相同，工作条件完全不同。

Anthropic 官方在讲构建有效 agent 时说过一个很实在的经验：他们做 SWE-bench 编码 agent 时，花在优化工具上的时间比优化整体 prompt 还多。工具用相对路径会出错，改成强制绝对路径后模型用起来零失误。工具设计值得像人机交互界面一样投入，他们管这叫 agent 与计算机的接口（ACI）。

判断标准很简单：如果 agent 根本动不了——够不到该有的能力、跨会话丢上下文、环境间行为不一致、无法审计、权限过大、中断后无法干净恢复——第一个要查的就是 harness。

 

03 第二层 Loop：反馈决定工作“能不能收敛”

 

环境搭好了，模型能干活了，但还缺一样东西：它怎么知道自己干完了，干砸了怎么办。

每个用工具的 agent 体内都有一个微小的内置循环：调模型、看结果、跑工具、把观察喂回去、重复直到完成。Loop engineering 干的事，就是在这个行为周围有意设计额外的循环。不是“再问一次”，不是“重试一下”，而是一套真正的工作-反馈系统。

一个好循环有七个零件：

触发——什么开启新一轮？用户请求、测试失败、新文档、定时任务、webhook、评估器反馈。

目标——我们要达到的具体条件是什么？不是“持续改进”，而是一个真实可测的靶子。

状态——下一轮需要知道什么？当前草稿、上次尝试、工具结果、错误、进度。

动作策略——agent 被允许做什么？编辑、委派、调工具、花 token、写文件、开 PR。

证据——怎么知道做成了？测试、schema 校验、引用、diff、指标、评审人批准。

反馈——到底哪里失败了？反馈必须紧凑、可行动。

停止规则——什么时候结束？成功、超时、预算耗尽、达到最大重试、不可恢复失败、升级给人。

Loop 工程最重要的一条原则，我建议你抄下来贴在工位上：

 

“不要基于信心循环，要基于证据循环。

 

“agent 说它做完了”不是停止条件。真正的停止条件长这样：测试通过、schema 校验通过、引用能解析、评审人批准、策略检查干净。

为什么 loop 不是 prompt 工程？因为 prompt 只决定一次调用里模型做什么，loop 决定调用之后系统做什么——怎么检查结果、怎么应对失败、怎么保存进度、怎么决定继续、怎么终止。Prompt 改进一次响应，loop 改进一个流程。这是两个完全不同的工程问题。

LangGraph 官方文档把错误处理分成了四类，就是 loop 设计的教科书案例：瞬时错误（网络、限流）交给系统自动重试；LLM 能自己恢复的错误（工具失败、解析问题）把错误写回状态让模型看到后调整；缺信息需要用户输入的用 interrupt 暂停等人；重试耗尽后的失败走补偿分支。注意最后一类——重试不能无限，必须有上限、有预算、有补偿路径。

如果 agent 几乎能用但不稳定——首稿接近但弱、成功时灵时不灵、重试失控、拿不出完成的证明——你要修的是 loop，不是换模型。

 

04 第三层 Graph：拓扑决定流程“能不能受控”

 

现在到最容易被过度使用、也最容易被误解的一层。

Graph engineering 把工作流结构显式化。它回答的不是“agent 应该做什么”，而是“下一步允许发生什么”。在图里：步骤是节点，转换是边，分支是显式的，并行是显式的，汇合是显式的，重试是显式的，人工打断是显式的。图成了整个系统的控制地图。

真正做 graph 的人设计的是这些东西：节点边界（什么属于确定性函数、什么属于 LLM 调用、什么属于专家 agent、什么属于人工评审）、状态 schema（每个节点能读写什么）、路由条件（什么证据让任务前进、后退、旁路、升级）、并发（什么能并行、什么必须等）、循环与出口（哪里允许重试、最多几次、怎么停）、持久化（检查点在哪、中断后怎么恢复）。

LangGraph 的实现方式很直观：节点就是 Python 函数，接收状态、返回更新；状态是共享内存，官方有个硬建议——state 里存原始数据，不要存格式化文本，prompt 在节点内按需拼。路由用条件边决定去向。

但图不是万能的，它有明确的边界：图在流程包含真正的分支、审批、专家交接、并行、恢复路径时才有价值；如果任务只是“给一个 agent 几个工具让它自己干”，一套扎实的 harness 加几个 loop 就够。图增加了清晰度，也增加了结构。结构加太早，系统会变得脆弱。

这其实是行业共识：Anthropic 官方也反复强调，从最简单的方案开始，只有复杂度确实带来收益时才往上加。

 

05 三层怎么配合：一个研究发布 agent 的完整拆解

 

单独看每一层都清楚，合起来才是真正的架构。用一个研究发布 agent 举例：它要选题、找资料、筛引用、写报告、过法务评审、审批通过后才能发布。

Harness 负责提供：浏览器访问、搜索工具、文件工作区、记忆、引用库、审批通道、trace、模型路由。

Loop 负责处理：证据不足时重试资料检索、修复引用失败、跑评分器检查、市场变化时刷新内容。

Graph 负责控制路径：选题 → 研究 → 筛选 → 综合 → 起草 → 评审 → 发布，发布前有一个人工闸门。

看出区别了吗？三层不是同一个东西换了个说法。它们协同工作，但各管一段。完美的图救不了烂 harness；强 harness 没有好 loop 照样烧钱；干净的 loop 一旦遇到藏在临时代码里的分支和审批，也会失控。

所以动手修之前，先诊断故障在哪一层：

• •agent 动不了 → 修 harness。缺工具、状态陈旧、记忆弱、权限坏、没有可观测性。
• •agent 几乎能用但不稳定 → 修 loop。首稿接近但弱、成功不一致、重试失控、没有完成证明。
• •流程本身复杂 → 修 graph。多专家、审批、分支逻辑、并行路径、结构化交接。

 

06 五个高频错误，和一个可以抄走的检查清单

 

最后给你一组别人踩过的坑，每条后面都跟着怎么绕开。

错误一：过早建图。 团队常在一开始就画一个巨大的工作流，还没看到工作到底怎么表现。正确顺序：先用简单的 harness 跑起来，收集 trace，找到稳定模式，只把值得控制的部分显式化。

错误二：让同一个模型既写又打分，还没有防护。 自审能帮忙，但共享同一个盲区。优先确定性检查、分开的评审上下文、外部评估器；高影响动作加人工审批。

错误三：把“不断重试”当成 loop。 那不是循环设计，那是失控的成本泄漏。每个循环都需要：可测量的目标、真实的证据、重试上限、升级规则。

错误四：把 harness 当杂物抽屉。 工具越多不代表 agent 越好。太多工具带来选择错误、上下文噪声、可靠性下降、风险面扩大。好的 harness 不是拥挤，是精准。

错误五：编排出问题怪模型。 模型弥补不了坏掉的 API、陈旧的状态、缺失的退出条件、模糊的工具 schema、不可见的失败模式。修那个真正拥有故障的层。

然后是检查清单，评审时逐项过：

Harness：工具是否窄而文档化？状态是否持久？权限是否最小化？操作者能否暂停、检查、恢复？trace 是否可见？

Loop：什么证据证明成功？失败时返回什么反馈？允许重试几次？停止规则是什么？预算耗尽会发生什么？

Graph：哪些路径必须确定性？什么可以并行？人工闸门在哪？哪些状态是共享的？恢复路径从哪开始？

评估：能否回放真实 trace？能否对比版本？能否把改进归因到真实变更？

运营：是否在跟踪成本、延迟、失败率、干预率、生产任务成功率？

记住一句话就够：harness 让模型变得可操作，loop 让工作变得可迭代可验证，graph 让执行路径变得显式可控。三者谁也无法替代谁。

人们谈论 AI agent 时，总觉得突破点是模型。在生产里，真正的分水岭几乎从来不是模型，而是模型周围的那套系统：让它能干活的环境，让它能改进的循环，让它能在控制下运行的图。这才是玩具 demo 变成真实系统的路。

下次 agent 再跟你说“完成了”，别急着换模型。先问一句：这是环境的问题、循环的问题，还是流程的问题？