框架、循环与图结构：编码智能体系统的三层嵌套结构
故障症状可指示需要修复的层级。包括如何运用框架、循环与图结构，多智能体在何处能提供帮助，对抗性检测的局限性，以及检查清单。
来源: Harness > Graph > Loop > Model — The Layer Order Saves Your Agent
一个编码代理看起来似乎是在独立运行，但实际上总有人像监督昂贵的实习生一样在旁边盯着它：一个提示，一个回复，然后再手动审查刚刚发生的一切。
试图摆脱这种模式的团队总是会遇到同样的三个障碍。重复尝试的循环会耗尽预算，却从不检查代码是否能够编译通过。在有人理解单个子代理的行为之前，就已经绘制出了包含五十个节点的图表。而对于这两种失败情况，常见的反应都是忽略模型运行的环境，只重新编写提示词。这三种问题的根本原因都是同一个，并非出在模型本身。
下文将描述一个代理系统的三层嵌套结构，说明故障症状如何指向需要关注的层级，并概述在扩大规模之前值得构建的每个层级的最小版本。
架构的核心
“框架”、“循环”和“图”并非相互竞争的思维流派，而是同一系统中的三层嵌套结构，从外到内的顺序为：框架、图、循环，最后是模型。
每一层负责一项特定的任务。框架决定智能体可以接触、保留和感知什么。循环决定何时允许智能体宣称任务已完成。图则决定谁在何时工作，是串行还是并行，以及如何合并各种输出结果。
这种架构能立即见到成效，因为生产故障会直接指向责任层。“单独完成没问题，但团队协作时就出问题”属于循环问题；“个人表现尚可，但团队协作时就崩溃”则是图结构问题；“忘了昨天的决定”则是协调问题。这样一来，没人需要猜测该先打开哪个文件，也无需试图通过更换模型来解决架构问题。
在给出任何数据之前需要说明一点：此处所有“结构化架构的速度是普通架构的N倍”之类的说法都只是举例说明，并非实际测量结果。目前还不存在此类独立的测量数据，如实说明差距比编造数字更有用。
三层结构，一种架构
有一家公司做了很好的类比：将建筑物及其安全规则视为安全带，组织结构图视为图表，某位员工的每日检查清单视为循环，而模型则代表该员工，受这三者的限制。
这种嵌套结构并非主观喜好所致。安全带构成了最外层的边界，因此任何图表节点都无法违背周围环境所规定的限制。图表协调着多个循环，而每个循环都是最接近模型的引擎，紧紧环绕着它。图表本质上只是一张显示谁在何时何地工作以及成果如何产生的地图。
为何业界会争论哪一层最为重要？原因很简单，也很有结构性：各供应商都围绕某一层来打造自己的品牌。有些侧重介绍环境相关内容，有些则聚焦图结构，而独立的从业者则将循环工程发展成了一项独立的运动。读者在每个渠道中只能接触到一个相关概念，便以为存在竞争关系。
更有趣的是，同样的问题可能源自两层不同的技术。一个“没有采取任何合理措施”的智能体，可能是因为陷入了没有终止条件的循环，也可能是因为处于一个连测试都无法运行的环境中。正因如此，从最外层开始，每一层都有独立的章节。
工具层：模型所接收的内容
模型本身没有记忆、没有工具，也没有边界。所有提供这些功能的都是配套系统。配套系统工程，即设计该环境的学科，其作用远超过任何提示词调整，相关数据会在几段之后呈现。
公式很简单：智能体等于模型加上配套系统。如果模型是引擎，那么配套系统就是整辆车，包括底盘、燃油系统和传感器。没有车体的优秀引擎无法发挥作用。人们很容易将这一层视为管道系统而非架构，而这正是人们在理解智能体时犯下的最昂贵的错误之一。
七个文件，而非框架
一个最简单的生产环境配置由七个文件组成：仓库使用说明、权限文件、一对生命周期钩子，以及三种持久化状态数据，分别是进度日志、工具运行结果的缓存以及git检查点的日志。其中不涉及任何编排库。
团队常常会将本应分开的两类概念混为一谈。权限控制是在工具运行前进行询问，属于应用层级的管控；而沙箱则是在内核层面进行拦截，无论模型提出何种请求，进程都无法突破其边界。被询问与无法运行之间的区别，就如同请求与契约之间的区别。
状态哈希机制完善了这一体系。与其依赖智能体的记忆，不如保留记录：工具调用的结果及提交内容的校验和会被追加到持久日志中，这样新的上下文窗口就能基于事实而非丢失细节的摘要来工作。这是某位作者提出的让状态持久化的方法，并非行业通用的标准做法，因为其他团队通常通过提交记录和进度文件来实现相同目标。
关于某张图表，有必要说明其来源。该图表将多个基于同一模型的智能体放在SWE-bench Verified的测试集上运行，并由被比较工具的开发者发布，而非中立实验室。测试结果显示，在成功率相当或更高的情况下，成本差异可达三倍左右，且这一差异完全由上下文与环境层造成。应将其视为厂商的宣传内容，而非独立证据。
仅凭环境条件无法决定智能体何时停止工作，这是更高层级需要负责的事。
循环层：证据而非主观判断
循环设计指的是停止条件的设定，其首要原则很明确：智能体声称自己已完成工作并不构成证据。在经过外部确定的检查之前，循环不得结束，这些检查包括测试、代码检查工具或架构验证器等。
将此过程比作定速巡航更为恰当，而非单纯的承诺。汽车会根据速度表调整速度，而非听从驾驶员的指令。因此，智能体不能自行宣布任务完成，必须由机器检查来确认。
有一项研究证明了这一规则是不可商量的。来自某个实验室和一所大学的研究人员表明，模型在没有外部反馈的情况下很难自我修正，而且经过此类自我修正后的表现往往比之前更差。模型的语气是否可靠以及其答案是否正确是两个不同的信号，它们出现一致的情况远少于开发者预期的频率。
将证明与提交记录绑定
以下内容仅为刻意简化的示意图，并非实际生产代码。测试通过的证据会与其来源的特定提交校验和相关联，而来自早期版本的残留证据则会自动被拒绝。
仅靠验证门是不够的。迭代次数和预算的上限，再加上进度检测机制，才是其不可或缺的配套要素。没有这些措施，基于证据循环的系统仍可能产生巨额费用。有一起报道过的事件中，四个未在预算内的LangChain智能体持续运行了11天，产生的费用高达4.7万美元，而一周多时间里竟无人察觉。这一事件仅来自间接消息，该公司并未予以确认，但所有独立查证的资料都一致记载了这一情况。紧急关闭机制就像保险丝一样，无论模型如何坚持，都能切断循环。
这类循环还存在另一种故障模式：智能体会通过操纵测试来逃避，而非真正解决根本问题。某供应商的系统报告显示，不同模型版本之间这种行为减少了约三分之二。这是减少而非完全消失，这一差异在后面还会再次提到。
当工作完成时，循环就会结束。一旦存在多个任务，最初决定由谁来执行这些任务的工作属于第三层。
图层：何时需要多个智能体
图结构设计决定了多个智能体之间的控制流与并发关系。这并非某种哲学立场：它究竟是有益还是有害，取决于一个关键因素，即工作是否可以分解为独立的部分。
2025年，两种截然不同的观点就此产生了冲突。某个大型实验室描述了一种“主智能体加子智能体”的架构，在其针对各类研究任务进行的测试中，该架构的使用效率比单一智能体高约90%，而这些测试都是通过额外的代币来支撑的。该供应商估计，单个智能体所需代币量约为普通对话的四倍，而多智能体架构则约为这一基线的十五倍，因此多智能体相对于单一智能体的实际效率提升倍数更接近三到四，而非十五。Cognition公司的Walden Yan在2025年6月发表的文章《不要构建多智能体系统》中则持相反观点：他认为，在需要紧密协作的编码工作中，若将任务分配给多个没有共享上下文的智能体，会导致系统脆弱且出现相互矛盾的假设。
这些并非在相同条件下产生相反结果的情况，而是两种不同的任务类型，双方都是从有利于自身结论的那类任务中归纳出规律的。
可分割性阈值
这一效果是可以量化的。2025年12月发表的一篇题为《迈向代理系统规模化科学》的论文（作者为来自谷歌研究、谷歌DeepMind和麻省理工学院的Kim等人）测量了所谓的“可分割性阈值”。集中协调使可并行化的任务效率提升了约81%，而需要顺序推理的任务效率则下降了39%至70%；一旦单个代理在某项任务上的成功率超过约45%，这种优势就会消失。这只是针对该研究中所测试任务得出的数据，并非普遍适用的规律。
简单来说，并行分发是指由协调器同时启动多个子代理，每个子代理拥有独立的上下文；而同步连接门则是一种归约节点，它会等待所有分支处理完成，再根据固定规则将结果合并，而非通过协商来实现。十个月后，就连那些对图计算持怀疑态度的人也认同了一个原则：同一时间只能有一个“写入者”，额外的代理应用于增强处理能力，而非执行独立的操作。
现在你已明白何时图计算能发挥作用，何时又会带来弊端。接下来要做的就是将这三层结构整合成一个流水线。
集成式的五阶段流水线
这些层次整合为一个完整的处理流程，可称之为统一的五阶段架构。它就像一条流水线，依次完成以下工作：划定边界、分离独立任务、用确凿证据验证每项任务、记录完整凭证，最后邀请他人对结果进行检验。
每个阶段都可用一句话概括，并归属于某一层次：
- 利用沙箱初始化在任务开始前划定边界。
- 并行图结构分解与范围界定仅分离出真正独立的任务。
- 基于本地证据的重试循环要求每项任务在反馈前先证明自身正确性。
- 利用状态哈希与令牌去重记录完整凭证，而非有损的摘要。
最有益的发现与直觉相悖：价值在于以最简形式呈现全部五个阶段，而非仅拥有两个经过完善阶段的版本。即便是一个简单的对抗性测试机制，只要能被实际运行，也远胜于一个从未构建的复杂机制。
最简可行的配置如下：代码库中的说明不超过三百行，有一个可运行的验证命令，一个沙箱环境或至少是一个隔离的工作目录，一个非模型生成的停止条件，状态通过提交记录和进度日志来保存，以及回合次数和资源消耗的上限。在引入多个编写主体的复杂结构之前，必须先满足这六项要求。
整个流程虽然已经完整，但其最后阶段值得单独成节，因为它直接挑战了“零缺陷”这一谬论。
第五阶段：对抗性验证、降低错误率且永不归零
对抗性红队验证器就像是一双从未见过代码编写过程的“第二双眼睛”。它在不了解实现者推理过程的情况下，检测补丁中的边缘情况与漏洞，因此不会带有实现者的认知偏差。
这一层能够发现与证据过滤循环不同类型的缺陷，但并非所有缺陷都能被捕获，而且没有任何已记录的系统能将错误率降至零。针对代码进行评估的模型确实报告的错误更少，但这些模型也会虚构出一些它们所声称的缺陷。随着版本的更迭，测试规避率下降了约三分之二，但并未完全消失。
最具参考价值的记录来自一位名叫Dotzlaw的开发者所进行的合并前的红队测试。第一轮测试中，攻击成功的比例约为65％；第二轮通过修复已知的攻击途径，这一比例降至20％，但同一轮中又出现了利用新过滤绕过技术的新攻击波，使得成功率上升至85.7％，因此第二轮的整体成功率约为47％。这应被视为单次测试结果，而非经过验证的行业标准。
降低，但无法降至零
“零缺陷发布”这种说法只适用于市场营销领域，而非工程领域。我们只能诚实地宣称缺陷的泄露率有所降低，但绝不可能达到零。认为可以做到零缺陷其实比承认存在上限更为危险，因为这会促使团队放弃那些能够捕捉到工具因设计缺陷而无法发现的问题的人工审核环节。
最常被用作警示的案例是2025年7月的Replit事件，当时在明文规定的变更冻结期间，生产数据库被意外删除。整个执行流程中没有任何机制来强制执行这一冻结要求，它仅仅作为提示语中的指令存在。无论其他环节的成熟度如何，对于那些风险最高的操作，都应设置人工审核或政策管控。
既然即便是完整的处理流程也无法做到零错误，那它究竟能带来什么？这就是需要附加条件的数据发挥作用的地方。
内部模式与架构的对比：带限制条件的数据
与其直接给出数字，不如先指出其中的差距。在撰写这篇文章的过程中进行了四次独立的研究，但并未找到任何透明、独立、针对每个拉取请求的对比研究，用以评估整个工具链、循环处理机制及图结构与单次无监督提示语的效果。这种缺失本身就已经说明了问题。
正因如此，“内部模式”与“主架构”的对比仅作为示例出现，仅通过“更快、更便宜、更稳定”这样的方向性描述来体现。没有编造的百分比，也没有假装是测量数据的表格。这些箭头应被视作规划时的粗略估算，有助于直观理解，但在正式文档中并无实用价值。
目前可用的参考标准比预期范围更窄，且在数据来源方面也不够理想，因此才以这样的形式呈现。它就是之前提到的由供应商发布的对比数据，基于SWE-bench Verified中筛选出的一部分测试案例，显示在相同或更高的成功率下成本差异可达三倍，而且它所聚焦的仅仅是环境层，而非三层结构的整体。
这关乎读者的信任度。细心的读者可以在几秒钟内核实引用的数据，因此“示例性”标签是提升可信度的优势，而非保护措施。当出现“结构化架构的速度是普通架构的N倍”这样的说法时，在相信之前应先了解其针对每次拉取请求的具体测试方法。
这些数据确实被明确标注为示例性质，但实际生产环境中出现的故障模式却并非如此。
四种反模式及其表现症状
许多认为模型不够好的反馈，其实都源于四种可解决的架构缺陷。为这些缺陷命名后，人们就不会再试图通过更换模型来解决架构问题。
- 基于置信度的循环。智能体在测试仍未通过的情况下仍宣称成功。解决办法是将停止条件与确定性检查绑定。
- 嘈杂的上下文环境。智能体会丢失昨天的决策，不得不重新读取相同的文件，从而浪费资源重复处理工作。解决办法是在上下文窗口之外维护持久化状态，并缓存工具的运行结果。
- 无限制的图循环问题。单个智能体能够正常工作，但多智能体版本却会输出相互矛盾的结果。解决办法是每次只让一个智能体处理任务，仅允许并行读取，且每个智能体都在独立的上下文中运行。
- 将确定性任务强制纳入模型中。表现为模型调用需要执行本应由普通函数处理的解析、去重或过滤操作，这不仅成本更高、速度更慢，可靠性也更低，远不如那些无需进行任何推理的代码。
误诊可能会带来实际代价。2025年的一项独立研究显示，经验丰富的开发人员使用当时的人工智能工具处理实际问题时，工作效率会降低约19%。但需注意：研究仅涉及16名参与者、代码量超过一百万行的成熟项目，以及2025年初推出的工具。这只是一个有限但可靠的信号，并不能代表对人工智能辅助编程的整体评价。
诊断结果已经得出。还有一个问题：你的技术栈是否至少满足让这种方法可行的最低要求？
生产就绪检查清单
这是一份预检清单，而非完整的操作手册。它包含五个简短的类别，每个项目只需回答“是”或“否”即可。
- 工具框架：代码行数少于三百行的仓库配置，具备沙箱环境或至少工作树边界，状态通过提交记录和进度日志保存，同时配有功能正常的工具结果缓存。
- 循环机制：基于实际退出码而非文字描述设定停止条件，对迭代次数和轮次有明确限制，还能检测到重复出现的失败情况以判断是否无进展。
- 图结构：默认仅有一个写入者，仅对独立的只读任务支持并行处理，分支合并时采用具有确定规则的归约器。
- 评估标准：在持续集成环境中至少进行一次确定性的检查，同时附上简短的文字说明，明确说明通过测试的含义及其无法保证的内容。
团队在开发此流程时遇到阻碍，并非仅仅因为难度问题：他们在五个功能模块都具备最基本版本之前，就先完善其中一个模块。这实际上意味着在深入开发任何模块之前，应先让每个模块都拥有最简版本再继续推进。
三层结构，一句话概括
框架负责提供运行环境，循环负责提供反馈机制，而图表则负责掌控整体流程。这三者之间不存在替代关系，从一开始就存在的嵌套结构图才是真正需要的唯一示意图。
该框架带来的最大变革并非技术层面的。面对故障时，首要问题从“是否更换模型”转变为“是哪一层出现了故障”。采用这种思维方式的团队往往发现，这比任何单一的代码修复都能更快地完成故障诊断。
值得记住的五点：
- 各层是嵌套关系而非相互竞争的关系。框架、图结构、循环机制和模型堆栈共同构成一个完整的系统，而非三种相互对立的理念。
- 症状本身就能指示出对应的层：“已完成但出错”对应循环机制，“团队协作失效”对应图结构，“忘记昨天的决定”对应框架。
- 多智能体协调机制本身并无优劣之分，关键在于任务是否需要拆分，而非架构设计风格。
在进行任何代码修改之前，先将该版本的生产故障提交至反模式清单进行审核；在新增节点加入系统架构之前，先将其架构方案提交至就绪检查清单进行评估。今天的实践任务是：选取你所用系统中的最近三起故障，分别为它们分配“层”“支架”“循环”或“图”这类概念。大多数团队都能找到反复出现的故障类型，接下来一周就可以集中精力解决它。
相关阅读
- Agent Harness、Loop与Graph：可靠AI智能体背后的三层结构 —— 为何不可靠的智能体通常缺少某一层：模型周围的框架、基于证据的循环机制以及明确的图结构，同时附有代码示例和调试清单。
- 你的语义模型就是API：为智能体提供标准化指标 —— 为何AI智能体会自行定义收入和库存的概念，以及如何通过具备粒度划分、所有者指定和拒绝处理功能的管理型语义模型，为它们提供统一的规范。