Harness与Loop的职责边界划分

可视化演示

展示AI Agent架构中Harness工程脚手架层与Loop推理循环层的职责边界划分、控制流归属、以及多Agent共享Harness独立Loop的分层实践，通过交互切换理解架构分层原则。

层级定位

经理站在餐厅门口，目光扫过整个大厅——今天客流如何、库存还够不够、服务员排班是否合理。他思考的是“整体”：这家餐厅要往哪个方向走。而走进后厨，厨师们正沿着流水线作业，每个订单来了就按固定流程处理：读订单、配菜、下锅、摆盘、喊服务员上菜。他们在意的是“当前这一步”：这道菜做好了没？

在AI Agent架构中，这种分工被清晰地划分为两个层次。Harness层就像那位经理，它是整个任务执行的编排者——定义任务目标、选择执行策略、管理生命周期、协调多组件协作。Loop层则像后厨流水线，它以循环方式驱动Agent执行：让大模型生成下一步决策，调用工具获取结果，观察环境反馈，然后再次进入推理。这个循环会一直持续，直到任务完成或Harness下令停止。

划分两者的边界，核心在“职责”而不在“代码量”。我们可以用系统总复杂度的分配来理解：

经理管方向、后厨管执行，这句话翻译成架构语言就是：Harness定义“做什么”，Loop负责“怎么做”。当你在代码评审中看到Harness里出现了“这一轮调用哪个工具”的硬编码，或者Loop里出现了“任务是否应该继续”的判断，就该意识到——越界了。

控制流编排

餐厅经理每天要做很多决策：今天是否开启午市套餐？客流量大时是让顾客排队还是开放预订？后厨的出菜顺序先后如何？这些决策有一个共同特征——它们发生在“动作之前”，属于流程级别的控制。而后厨并不会思考“今天该推什么套餐”，它只关心手上这道菜怎么做。

控制流的归属，是Harness与Loop分工的第一条分界线。Harness负责所有流程级决策：任务启动与终止条件、分支路由（走工具调用还是走人工确认）、并发策略（多个Loop并行还是串行）、重试与退出逻辑。Loop负责迭代级决策：当前这一步调用哪个工具、大模型生成的参数是什么、观察到的结果如何暂存。

为了看清这种分工的数学本质，我们可以把一次任务执行建模为状态转移与动作选择的分离：

$f$ 写在Loop里，$g$ 写在Harness里，这就是控制流的归属原则。一个良好的系统，其流程决策应该是可预测、可审计的——就像一家有标准作业手册的餐厅，任何一位厨师长上任都能保持出品稳定，因为“什么菜先上、什么情况插单”由经理的制度决定，而不是由某个厨师的临场发挥决定。

状态管理

经理的办公桌上有一本全局账本，上面记录着餐厅的库存、销售额、人员考勤；而每位厨师面前只有一张小小的订单小票，上面写着这道菜的要求。经理和后厨都在“记录”，但记录的范围和生命周期截然不同。账本要保存三个月以便复盘，小票在出餐后就被扔掉。

Harness持有的状态包括：用户会话、多轮对话历史、任务级配置、可用工具列表、用户偏好。这些状态的共同点是——跨越多次Loop迭代而存在，需要全局可见。Loop持有的状态包括：当前迭代的大模型输出、工具调用参数、上一步的观察结果、本轮的错误信息。这些状态在迭代结束时就完成了使命，不需要全局保留。

状态管理分工有一条黄金法则：只有需要跨迭代共享的数据才上提给Harness，其余一律留在Loop内部。用集合的视角来看：

这和餐厅的账本逻辑完全一致：经理不需要知道某一盘菜里葱花是怎么切的，但必须知道整个厨房的库存水平。当你在代码里看到Loop把某一轮的模型输出写进了全局状态，或者在Harness里查不到任何关于任务进度的记录，那一定是状态管理出了偏差。

错误处理

某天，后厨火候没掌握好，把一份招牌菜做糊了。厨师不会沉默地自己重新做——万一食材不够呢？更不会直接给顾客换菜。他会立刻报告经理，由经理根据情况决策：食材充足就重做；食材不够就换一道同等价位的菜；如果顾客已经在投诉了，可能直接免单并送一份甜点。错误处理从来不是执行者一个人的独角戏。

AI Agent场景中，错误处理是Harness与Loop协作最密集的环节。Loop负责“检测与上报”：发现工具调用失败、模型输出格式异常、超时等情况，收集剩余上下文并向上抛出。Harness负责“决策与恢复”：评估错误的严重程度，选择重试、换工具、降级方案或终止任务。

重试策略是错误处理的核心。假设单次执行成功的概率为 $p$，系统最多重试 $k$ 次，那么最终成功的概率为：

Harness需要决定 $k$ 的取值：$k$ 太小，错误恢复的概率不够；$k$ 太大，可能浪费算力甚至放大损害（比如重复扣款）。关键原则是：Loop把错误原样上报，重试和降级的决策留在Harness。那些“在Loop里悄悄重试三次”的做法，就像厨师自己把做糊的菜重新炒一遍——经理根本不知道发生了什么。

接口契约

菜单是餐厅里最神圣的文件。后厨按菜单做菜，服务员按菜单下单，顾客按菜单点餐。菜单上写着“宫保鸡丁”，后厨不会做成“番茄炒蛋”，服务员也不会拿它去哄客人。菜单就是一份契约，它让各方不需要了解彼此的内部细节就能顺畅协作。

Harness与Loop之间同样需要一份“菜单”——接口契约。契约定义了三个核心维度。第一是协议定义：Loop向Harness注册自己的输入输出Schema，Harness通过Schema向Loop下发任务。第二是数据边界：哪些数据由Harness传入Loop，哪些由Loop返回Harness，哪些数据Loop严禁修改（如只读配置）。第三是事件通知：Loop执行中需要向Harness发送事件，如“步骤完成”“遇到错误”“需要人工确认”，这些事件的类型、载荷和时序要提前约定。

契约的稳定程度直接决定系统的可维护性，可以用兼容率来衡量：

维护好接口契约后，Harness更换大模型供应商、Loop增加新工具，双方都能像餐厅换食材供应商一样无感。一个反例是：Harness直接读取Loop内部的数据结构字段，或者Loop在没通知Harness的情况下改动了返回格式——这就像服务员绕过菜单直接向后厨喊“今天做点你拿手的吧”，短期方便，长期灾难。

可测试性

餐厅出新品时，后厨会在操作台上单独试做几份，让内部试吃专员评价——这叫单元测试。在正式上线新菜单前，餐厅会组织一次全员模拟演练：服务员、厨师、经理甚至收银员全部到场，按真实营业流程走一遍——这叫集成测试。这样就不用等到真实营业时才发现“这道菜要15分钟，可菜单承诺10分钟上菜”。

Harness与Loop的测试策略同样可以分离。测试Harness时，将Loop替换为Mock对象——就像试菜时让一位经验固定的替班厨师上场，保证后厨行为可控。测试Loop时，不依赖Harness的具体实现，只给它标准的测试输入，就像给厨师一份拿手的菜单让他发挥。除了这两类测试，可观测性（日志、追踪、指标）贯穿始终，相当于给餐厅装监控摄像头，出了问题能回放到底哪一步出了岔子。

用成本来评估测试策略是否健康：

一个架构是否健康，可以看 $T_{mock}$ 的占比：如果Mock成本高得离谱，往往说明契约耦合太深，测试时不得不伪造大量状态。反之，当你能轻松地用Mock替换掉Loop来测试Harness的决策逻辑，就像用替班厨师试菜一样，说明两者的边界非常干净。

性能维护

最糟糕的餐厅是什么样？经理心血来潮冲进后厨亲自颠勺，指令和下厨指令混杂在一起；厨师看见前厅排队太长，擅自改了菜单、换了烹饪流程。结果就是菜做乱了、账记混了、顾客投诉了。职责重叠是复杂系统腐化的第一步。

当Harness开始直接操作Loop的迭代细节（比如硬编码某一次工具调用的参数），或者Loop开始自己决定要不要重试、要不要退出循环，架构的边界就开始模糊。这种职责重叠会带来三类问题：性能瓶颈——全局状态被高频读写，每次迭代都做无谓的序列化和同步；调试困难——一个bug无法定位属于哪一层，既像Harness决策错又像Loop执行错；演进风险——改一处牵一发动全身，任何重构都要同步修改两层。

用控制流复杂度 $M$ 来量化系统的混乱程度：

为了让系统长期可维护，建议用架构评审来守住边界。每一次重构都问一句：这个决策属于Harness还是Loop？这个状态该放全局还是局部？这道菜该由经理定夺还是后厨自理？当团队里每个人都能不假思索地回答这些问题，你的Agent系统就拥有了像那家理想餐厅一样的分工美学——经理安心管大局，后厨专注炒好每一道菜。

AI 应用场景

Python 演示

"""演示 Harness 与 Loop 的职责边界：Harness 负责流程决策，Loop 负责单步执行。""" import random  class Loop:    """执行循环：负责单步执行，不关心全局策略。"""     def __init__(self):        self.step_count = 0     def run_step(self, task):        """执行一次迭代：模拟模型推理+工具调用。失败时向上抛出。"""        self.step_count += 1        if random.random() < 0.2:            raise RuntimeError("工具调用失败")        return {"step": self.step_count,                "result": "完成" + task + "的第" + str(self.step_count) + "步"}  class Harness:    """高层编排：决定循环何时停止，处理 Loop 上报的错误。"""     def __init__(self, loop):        self.loop = loop        self.max_retries = 2        self.max_steps = 5     def execute(self, task):        """执行完整任务：控制循环边界，错误重试与降级。"""        results = []        while self.loop.step_count < self.max_steps:            retry = 0            while retry <= self.max_retries:                try:                    results.append(self.loop.run_step(task))                    break                except RuntimeError:                    retry += 1            else:                print("重试耗尽，切换降级策略")                break        return results  if __name__ == "__main__":    runner = Loop()    boss = Harness(runner)    output = boss.execute("处理理赔申请")    for item in output:        print(item)

1. self.step_count = 0Loop只维护自己的迭代次数，不保存任务全局信息，就像厨师只看订单小票。
2. while self.loop.step_count < self.max_steps:循环何时停止由Harness判断，Loop自身没有退出机制。
3. raise RuntimeError("工具调用失败")Loop把错误原样抛出，不自己消化，对应“检测与上报”。
4. while retry <= self.max_retries:Harness决定重试次数上限，Loop无权修改重试策略。
5. print("重试耗尽，切换降级策略")重试无果后Harness执行降级决策，这是编排层的专属权力。

常见误区

面试题