数据研发Multi-Agent架构的Harness工程实践


一、为什么需要Harness

一个让人尴尬的常见场景

不知道你有没有过这种体验:花了两周搭了一个数据研发Agentdemo,给老板演示的时候那叫一个丝滑,用户提个需求,Agent自己分析、写代码、跑测试,五分钟搞定。老板看完一拍大腿说"上!下个月就让团队用起来!"。

然后你信心满满地把这个东西交给团队,第一天就出事了。同事甲说:"我让它做个简单需求,结果它跳过了关键确认步骤直接写代码,写出来的东西完全跑偏。"同事乙说:"它把上一个需求的字段名带到这个需求里来了。"同事丙更绝:"我让它修一个小bug,它把整个表重新设计了一遍。"还有同事追着说各种问题:"产出表PK不唯一、表命名不符合规范、线上代码注释和参数被清空了、线上代码改出了bug、产出代码语法不通过"等。

你一查日志,发现Agent确实"理解"了需求,"完成"了任务,代码看起来"很美",每一步看起来都"合理",但合在一起就是不对。最要命的是,下次同样的场景,它可能又是另一种错法,你连复现都复现不了。

这种感受,我相信做过Agent的人都不陌生。

真正的核心问题

所以问题到底在哪?我们慢慢琢磨明白一件事:Agent能跑,不代表能用;能用,不代表可信。

"能跑"是说在理想路径上,输入A能给出输出B,demo阶段都能做到。"能用"是说面对各种乱七八糟的真实输入,Agent不会跑偏、不会偷懒。"可信"是说出了问题不会崩、你能查、能改、能避免下次再犯,团队敢把它放在关键流程里。从能跑到能用,再到可信,中间隔的不是模型能力的差距,而是工程能力的差距,把同一个模型给两个不同的团队用,做出来的东西仍可能天差地别。

这就是数仓场景里AI提效最难的地方。「能写出大致正确的SQL」和「能交付一张生产级数仓表」之间,差着一整个工程体系。前者是模型能力问题,后者是Harness问题。

这个问题的本质,是LLM的context压缩机制天然不擅长保持长程约束。临时口头说的口径、规范、约束,会随着token接近上限被压缩进摘要里失真甚至消失。而数仓场景对长程约束的依赖远比一般领域大——一条「金额字段统一用DECIMAL(22,6)」的规约,可能要在30轮对话之后还能被严格遵守;一个「ds分区必须按yyyyMMdd字符串」的约定,可能要跨越「需求解析→模型设计→SQL编写→测试→上线」5个阶段都不能漂移。

既然LLM自己抗不住,那就只能把「抗」这件事从模型里挪出来:用一套确定性的工程框架托住。这就是Harness的核心命题——LLM负责理解和创意,Harness负责约束和验证。

二、AI工程范式演进

要理解Harness的位置,得先看清楚我们这几年是怎么一步步走过来的。

第一代:Prompt Engineering——把话说清楚

最早大家研究的就是prompt怎么写。各种技巧层出不穷:扮演专家、思维链、few-shotexample、把任务拆成步骤,一时间"prompt工程师"成了热门职业。

这一代解决的核心问题是:怎么让模型理解我想要什么。

在那个阶段,模型本身的指令遵循能力还不够强,你不字斟句酌地写prompt,它就会跑偏。所以prompt engineering是必要的。

但prompt engineering有个天然的天花板:它假设你只跟模型聊一次,问完即走。一旦任务复杂、需要多步、需要外部信息,光靠prompt就不够了。你prompt写得再好,模型脑子里没有相关知识,它还是只能瞎编。

第二代:Context Engineering——喂对信息

于是大家开始研究怎么给模型"喂料"。RAG火了起来,向量检索、文档切片、重排序,这一套组合拳成了标配。再往后发展,工具调用、functioncalling、MCP协议,让Agent能主动去拉数据、调API。

这一代解决的核心问题是:怎么让模型在做决策时,看到该看的、不被无关信息干扰。

Context engineering比prompt engineering高了一个维度:它不只是优化"怎么问",而是优化"问的时候手里有什么牌"。这一阶段我们也确实看到了Agent能力的飞跃——以前不能做的现在能做了,以前要人工查的现在Agent自己能查。但是,仅靠这两代还是不够。你会发现:

  • Context给得再好,Agent依然会在某些路径上犯低级错误。

  • 同一个需求跑十次,可能有八次都对,剩下两次错得离谱。

  • 出了问题之后,你不知道是哪一步出的,更不知道怎么防止再犯。

这些问题,都不是再调一调prompt、再多塞点context能解决的。它们是系统性问题,需要系统性方案。

第三代:Harness Engineering——让Agent可控制、可预测、可信任

Harness这个词原本是马具的意思——你让一匹烈马拉车,光有马是不够的,还得有缰绳、笼头、车辕、车架,把马的力量约束在你想要的方向上。Harness Engineering要解决的核心问题是:怎么让Agent的能力以可控制、可预测、可信任的方式发挥出来。这里有几个关键点:

  • 可控制:你能在关键节点介入,而不是Agent自顾自一路狂奔

  • 可预测:同样的输入,行为模式应该是一致的,不会今天这样明天那样

  • 可信任:输出结果必须合理;出错之后能从某个中间点继续,而不是整个流程作废

如果说Prompt Engineering是问"怎么把话说清楚",Context Engineering是问"给Agent看什么资料",那Harness Engineering问的是更进一步的问题:Agent到底应该怎么工作。

核心公式

Harness工程实践相关文章一直在强调一个公式:Agent=Model+Harness

Model是能力的来源,Harness是能力的释放方式,可以理解为Agent中除了基础模型,其余皆为Harness。模型决定了上限,Harness决定了下限。模型能力具有“天花板效应”,长时任务更具备“裸模型陷阱”和“累积误差”。

这两年模型能力的进步太快,让很多人产生了一种错觉,觉得"等模型再强一点,所有问题都能解决"。这是不对的。模型再强,没有Harness兜底,你照样不敢把它放进生产系统,Anthropic在实测中发现即使顶尖模型Opus系列在跨上下文任务中仍会出现看到部分进展就宣告完成不验证的情况。反过来,Harness做得好,哪怕模型差一点,你也能跑出靠谱的产品。

三、Harness架构设计

其实小到Claude.md或Agent.md文件,大到Qoder、Claude Code、Codex等企业生产级Agent系统,我们都可以说有Harness工程理念的存在。作为一种工程范式,Harness概念非常广泛,我们难以概括其全貌,这里我们只分享下自己的实践经验。

整体架构图

Harness工程应该怎么设计,才能保障Agent的能力可控制、可预测、可信任呢?下面我们结合业界公开理念和自己的数据研发Multi-Agent实践,将其中应用到的Harness工程理念拆分成核心三大分层和六大支柱来详细讲解,整体架构图如下:

核心分层

我们按照Multi-Agent执行生命周期将围绕它的Harness工程拆分为身份层(Agent执行前的静态身份与约束定义)、执行层(Agent执行时动态决策的执行路径、加载上下文、门禁检查、状态追踪、故障恢复等)和进化层(Agent执行后的经验沉淀与进化),层级关系如下:

  • 身份层→执行层:身份层圈定Agent"能力边界",执行层在这个围栏内运转,身份层告诉执行层"谁干什么,哪些路能走,哪些路不能走"。

  • 执行层→进化层:执行层产出执行过程中间产物并进行质量门禁检查,当执行出故障或暂停时,依赖状态信息决定"退到哪重来";每次故障恢复,都是一条"错误样本",进化层吃进这些信号,通过经验升级沉淀为知识。

  • 进化层→身份层:知识进化的产出最终落地为:更精确的身份定义、更严格的行为约束体系,下一轮执行,身份更明确、边界更清。

一句话总结递进逻辑:身份定形→可靠执行→进化增强→身份增强(螺旋上升)。去掉身份层,系统不知道该怎么工作;去掉执行层,过程不可控、产出不可信;去掉进化层,系统永远停在原地。

核心支柱

我们根据MECE原则拆分出Harness的核心六大支柱,依托三大分层,它们形成了一条闭环反馈链路。我们总结了六类可能导致系统不可预测、不可控、不可信的问题,每类问题对应一个支柱,缺失任何一个支柱都会导致一类不可接受的系统性故障。如果去掉Identity,Agent不知道自己负责什么;去掉Orchestration,Agent不知道自己该干什么;去掉Context,Agent不知道关注什么;去掉Gate,过程产出不知道是否可信;去掉Recovery,错误不会被系统化地恢复;去掉Evolution,错误只是被处理了但没留下痕迹。

具体问题

根因类别

对应支柱

Harness层

级

支柱定义

Agent 越界发挥,本该写需求文档的去画架构图了;表命名不规范、PK 不唯一、分区格式漂移

角色和能力边界不清、约束体系不够强

Identity

身份层

定义"谁有什么能力、什么绝对不能做,什么可以做,如何做",负责明确角色定义与约束体系

简单需求也要走完全链路,用户等不了就不用了

流程缺乏弹性和效率

Orchestration

执行层

定义"按什么顺序执行",负责流程编排和智能调度

上一个需求的字段名串到这个需求里来了


上下文污染和信息管理失控


Context

定义"什么信息在 Agent 间流动",负责上下文工程

Agent 觉得"这次很简单"就跳过了检查,结果翻车

缺乏强制性质量验证

Gate

定义"做得好不好",负责门禁检查与质量评估

流程中断或子任务失败后导致从头开始,之前 30 分钟的工作全废了

没有中间状态、无法支持断点恢复和分级故障恢复

Recovery


定义"当前在哪、下次从哪继续、出错怎么恢复",负责状态存储和管理、保障故障容错和韧性

同一个坑反复踩,上周犯的错这周又犯了

错误没有工程化为经验

Evolution

进化层

定义"错误怎么变成经验",负责学习和进化


借助核心六大支柱,我们是如何保障Agent运行可控制、可预测、可信任的:

  • 可控制=能力边界+门禁检查:Identity出厂就焊死了"能做什么,不能做什么",Gate在关键节点设卡——"进得去也出得来,人随时能拉闸"。

  • 可预测=确定路径+确定输入:Identity确保"同一个角色永远做同一类事";Orchestration确保"给相同需求走相同步骤";Recovery确保"任何时候都能回答做到哪了";Context确保"每步决策看到的信息是确定的、可复现的"。

  • 可信任=质量兜底+持续改善:Gate保证"出不了大错";Recovery保证"错了也不会崩";Evolution保证"犯过的错不再犯,越用越好"——信任=当下靠谱+未来更靠谱。

四、Harness核心支柱

本章我们详细介绍下六大核心支柱,每个支柱我们单独会讲两件事:这个支柱是什么→我们具体怎么做的。

支柱一:Identity——角色定义与约束体系

理论概念

是什么:清楚定义Agent"是谁,负责什么","能做什么"和"绝对不能做什么"的边界,做的时候按什么流程。主要包括角色定义和行为约束体系两部分,角色定义就是Agent的身份说明,行为约束则是Agent执行时的规则或限制。

举个例子,你让一个新员工做事,最怕的是什么?最怕他什么都没做过,你给他一张白纸他无从下手;也最怕他什么边界都不知道,可能闯出大祸。最好的状态是什么?是他清楚知道:"这件事我必须做,那件事我绝不能做,中间这一大块我可以自由发挥。"边界清楚之后,他反而能放开手脚。同理,给Agent的约束越含糊,它的输出越不稳定。一旦把"必须做什么、不能做什么、可以怎么做"写清楚了,Agent的表现立刻就上来了。这背后的机制其实不难理解。模型本质上是在概率空间里采样,约束越清楚,采样空间越聚焦,输出的方差就越小。约束含糊,采样空间巨大,今天采到这边明天采到那边,结果当然不稳定。所以约束不是为了限制能力,而是为了让能力稳定地释放出来。

为什么重要:这是所有Harness的基础。Agent的"能力"不是它脑子里的,而是你定义出来的。你定义得清楚,它就发挥得清楚;你定义得含糊,它就乱发挥。

怎么落地:每个Agent要有明确的"能力说明书"和"行为约束体系",里面至少包含:

  • 身份定义:这个Agent的角色定位

  • IO定义:输入输出的格式

  • 能力说明:可以使用哪些MCP&Skill工具

  • 行为约束:处理任务的标准流程、哪些事情绝对不能做、约束如何划分层级

写这部分内容的过程,本身就是一次梳理。你会发现很多原以为"理所当然"的事情,写下来才发现根本没想清楚。

我们具体怎么做

第一件事:架构选型——Orchestrator+Specialist

我们采用了Orchestrator+Specialist(协调者+子专家)的Multi-Agent架构。为什么不让一个Agent干所有事?一个全能Agent,从头到尾把活干完。结果是全程上下文挤在单个会话中,越来越乱,模型注意力被高度稀释、Agent能力边界越来越模糊、出问题不知道是哪一步出的,就好比几年前你输入一段提示词让大模型返回输出,它中间做了太多杂七杂八的事情,即使有深度推理,最后的结果也可能与思考过程无法匹配,这导致结果难以追溯与解释。我们的数据研发"协调者Agent+子专家Agent"架构如下:

  • 协调者Agent:不写代码、不出方案、不做深度推理工作,只负责调度、把关、评审、汇报

  • 多个子专家Agent:有明确职责,例如需求拆解、方案设计、SQL开发、测试验证

第二件事:职责划分——角色定义与能力边界

协调者身上叠了6个显式定义的角色身份——调度员(决定派谁去干活)、澄清员(跟用户对齐需求细节)、审查员(评审每个Agent的产出)、门禁员(决定能不能进下一阶段)、汇报员(向用户同步进度)、重试员(出错时的回退处理)。这6个身份的职责边界、触发条件、不可越界的事项都必须明确声明。

四个专家Agent各自只暴露自己领域的能力——需求拆解Agent不写方案只出需求拆解文档、方案生成Agent不出SQL只出方案、代码生成Agent不擅自改方案只生码、测试Agent不越权修复bug,每个Agent只分配对应的MCP和Skills。这种"严格分工"带来的好处是:每个Agent的能力定义都很薄,反而稳,因为屏蔽了协调者的上下文,做事情更加专精化,只需要被协调者调用,在独立运行窗口中关注自己的输入内容、流程规范、约束体系等。

协调者的角色定位特别重要:它不是"老板",而是"项目经理+质检员"。它不能下场写代码,否则它就退化成了一个全能Agent,整个分工就崩了。

第三件事:行为约束——把"什么绝对不能错"和"什么最好别错"分开说

关于如何通过行为约束体系保障Agent可控执行,我们设计了一个三层金字塔结构:

最顶层:超级红线。数量很少,每一条都是"违反了就是严重事故"。比如不得跳过用户审查、不得编造数据、不得越界访问其他Agent的私有空间等。没有红线时,Agent经常"好心办坏事"。约束系统必须有相对"硬性"的部分。全是软约束的系统,Agent会用"我觉得"绕过去,这是用户难以接受的。硬性红线要写在最显眼的位置。举几个常见例子:

  • Human in the loop:阶段切换必须有用户确认(不能Agent自己觉得OK就跳过)

  • 禁止编造数据:知识库未检索到知识必须如实回答(不能Agent根据通用知识编造)

  • 禁止违背职责划分:协调者禁止直接产出方案或SQL代码(必须调用子专家Agent)

  • Sub Agent隔离:子Agent在独立会话运行(防止各环节上下文污染)

  • 避免认知污染:信息分舱,物理文件隔离(Agent只管自己的约束,不能用别人的教训约束自己)

  • 禁止跳过重要步骤:我们希望数据方案可以通过中心化平台管理,但是Agent经常跳过方案上传的步骤,后来我们引入红线,把那些"绝对不能跳过、绝对不能擅自决定"的事情明确写出来,跳过次数明显减少

中间层:错误记录。历史教训总结。这是系统进化的燃料,每次有人指出"这里你做错了",就记一笔。错误记录是需要引起重视的,告诉Agent"以前在这个地方栽过跟头,注意一下"。

最底层:操作规则。比如知识库检索流程、产出文档模板、错误处理的标准流程等。规则太多,Agent会"选择性遵守"。如果把各种规则、各种规范、各种最佳实践,洋洋洒洒上万字塞给Agent,结果是Agent对规则的遵守度反而下降了,因为Agent的注意力被稀释了。它没办法对每一条都同样重视,于是开始"选择性关注"——某些条目它当回事,某些条目它就忽略了。信息密度不能太高。重要的事…

— 以上为试看内容(约 40%),开通会员后阅读全文 —