Harness / Loop / Graph:agent 系统坏了,先分清坏在哪一层
本文原题《The 3 AI Agent Systems Every Builder Must Understand》,作者 rari(@0xwhrrari)——X 上长期写 agent 工程长文的独立作者。他的从业背景没有公开、我核不到,所以这篇的分量不在「他是谁」,而在于它给出的三层拆分,正好对上了海外今年在认真讨论的一个词:harness engineering(Addy Osmani 五月在 O'Reilly Radar 写过专文,学术侧也已经有综述在系统梳理)。中文翻译、重排、6 张配图本地化:Yaqin Hei(非原创,已保留原文出处)。
译者的话:为什么翻这篇
站内我已经翻过两篇讲 loop 的文章——Karpathy 那篇讲「为什么该造 loop」,Claude Code 团队那篇讲「四种 loop 分别什么时候用」。两篇都好,但它们合起来只覆盖了一层。真到线上出事的时候,我发现自己手里的诊断词汇只有两个:prompt 没写好,模型不够强。
这篇补的正是这两个之外的东西。它把一个像样的 agent 系统拆成三层:harness 给模型一个能干活的地方,loop 给这活儿一个反馈周期,graph 给这个过程一条明确的路线。平时三层挤在同一个脚本里,所以感觉可以互换;可一旦出事,该动的地方完全不同。
对我最直接的改变是排查顺序。以前 agent 出问题,我第一反应是回去改 prompt,改不动就想着换个更强的模型。现在我先问一句:这个失败归哪一层?「跨会话丢进度」是 harness 的事,再强的模型也记不住昨天;「第一版差不多、但不稳」是 loop 的事,缺的是外部证据和有限重试;「多步流程挂了却定位不到」是 graph 的事,缺的是和节点对齐的 trace。这三问下来,我至少省掉了两轮无效的 prompt 调优。
再补一条原文没法知道的事。文中把 OpenAI 的 Agent Builder 当成 graph engineering 的产品化范例——而这个范例已经要关了:OpenAI 在 2026 年 6 月 3 日把 Agent Builder 和 Evals 平台一起放进弃用列表,11 月 30 日下线(Evals 10 月 31 日先转只读),官方给的迁移路径是回到 Agents SDK。这反倒给原文那句「别在看懂这活儿之前就把流程图画死」加了个很硬的注脚:连画布本身都可能比你的业务流程先消失,所以先攒 trace,后固化路径。
你下周能直接用的有两样:中段那张「症状 → 该修哪一层」的诊断表,和文末那份上生产前的自检清单。
以下是正文
Agent 是怎么失败的
大多数 agent 系统失败,不是因为模型太弱。
是因为模型周围那套东西,从一开始就没被当成一个系统来设计。
工具不可靠。
state 在两次运行之间就消失了。
agent 一遍遍重试,却什么也没学到。
工作流的分支跑到了没人能检查的地方。
然后每一次失败都被算到模型头上。
这个诊断是错的。
一个认真的 agent 背后,有三层不同的工程:
- harness 给模型一个能干活的地方
- loop 给这活儿一个反馈周期
- graph 给这个过程一条明确的路线
它们互相重叠。
它们可以互相包含。
但它们解决的是不同的问题。
模型负责决定。harness 让它能动手。loop 逼它把结果证明出来。graph 管住下一步允许发生什么。
30 秒版本
Harness engineering 造的是模型周围的运行环境。
工具、记忆、文件、权限、沙箱、路由、检查点(checkpoint)、trace、人工审批,全都住在这一层。
(harness 这个词直译是「马具」——套在牲口身上、让它的力气能真正拉动车的那套装备。套在模型身上的那套装备,就是 harness。)
Loop engineering 设计的是重复的工作和反馈。
agent 先产出一个东西,拿它去对证据检查,收到一条有用的失败信号,然后在一条有边界的规则下再来一次。
Graph engineering 把控制流显式化。
它定义节点、分支、汇合(join)、并行、合法的循环、状态转移和退出路径。
记住区别最省事的办法是这样:
HARNESS = 环境
LOOP = 反馈
GRAPH = 流程
只要一个 agent 走出 demo、开始碰真实的文件、API、客户、钱或者生产代码,这个区分就立刻开始要命。
为什么大家总把它们混在一起
三层都围着同一个模型。
三层都影响可靠性。
三层里都可能出现某种看起来像循环的东西。
而在一个小原型里,三层通常全埋在同一个脚本里。
所以它们感觉可以互换。
并不能。
看一个最基本的、会用工具的 agent:
问模型
收到 tool call
跑这个工具
把观察结果回传
再问模型
干完就停
这个小循环属于运行时(runtime)。
但工具定义、文件系统和 state 存储属于 harness。
「测试 - 重试」的策略,是一个 loop 设计决策。
在研究员、审稿人和发布者之间怎么选,是一个 graph 设计决策。
一份软件可以同时装下这三层。
而最干净的架构,是从先给它们各自起个名字开始的。
第一层:Harness Engineering
一个裸模型能把输入变成输出。
它没法自己维护项目 state、跑一套测试、检查浏览器、安全地写文件、执行权限,或者明天接着今天停下的地方继续。
这些能力是 harness 给的。
最简单的定义是:
模型是那份智能。harness 是让这份智能变得有用的那套机械。
把模型从你的架构图上拿掉。
剩下还能看见的东西,基本都属于 harness。
Boris Cherny 通过 Claude Code 反复指的就是这个转向:hook、定时运行、隔离的 worktree、自定义 agent、并行执行——这些都不是 prompt 技巧。
它们是 harness 的原语(primitive)。
一个像样的 harness 里装什么
Context
- 系统指令
- 检索到的知识
- 对话 state
- 任务策略
- skill 与操作规程
动作面(action surface)
- API
- 浏览器控制
- shell 与代码执行
- 数据库
- MCP 工具
- 专职 agent
持久化
- 文件
- 检查点
- 会话 state
- 进度日志
- git 历史
- 长期记忆
执行控制
- 超时
- 重试上限
- token 与成本预算
- 模型路由
- 交接(handoff)
- 审批闸门
安全
- 隔离环境
- 最小权限
- 白名单
- 密钥处理
- 人工授权
可观测性
- trace
- 工具的输入与输出
- 状态转移
- 成本与延迟
- 评估结果
Harness 工程在哪儿开始值钱
当一个任务的时长超过一个 context window,harness 的活儿就变成了关键。
一个连干几小时的 coding agent,不可能只靠聊天记录活着。
它需要另一个会话也能读懂的、能存住的产物。
一套好用的配置可能包括:
- 一个开工时先勘察工作区的初始化器
- 一个进度文件,写清楚什么做完了、什么还没
- 用 git commit 把能跑的状态固定下来
- 在有风险的动作之前打检查点
- 能产出清晰证据的验证工具
这不是一条更好的 prompt。
这是一个更好的工作环境。
当 agent 出现下面这些情况时,先从 harness 动手:
- 拿不到它需要的能力
- 跨会话就把进度丢了
- 权限开得太宽
- 换个环境行为就变
- 没法被暂停、检查或恢复
- 出了故障没人能复原现场
第二层:Loop Engineering
每个会用工具的 agent,内部本来就有一个小循环:
模型 -> 动作 -> 观察 -> 模型
Loop engineering 开始于:你有意识地去设计这个行为外面的那些循环。
目的不是让 agent 永远重复自己。
目的是把一次性的尝试,变成一个被管起来的过程。
验证 loop
最有用的那个外层 loop 其实很简单。
做出来
↓
对着证据检查
↓
过了吗? ── 过了 ──> 停
│
没过
↓
返回具体的反馈
↓
限次重试
这个检查可以是确定性的:
- 测试通过
- schema 校验通过
- 链接能解析
- 数字对得上
- 文件能编译
也可以需要一个审阅者:
- 论证是完整的
- 语气对得上受众
- 证据撑得住结论
- 改动的范围划得对
规则都一样。
不要围着自信心打转。要围着证据打转。
「agent 说它干完了」不是证明。
「测试通过了、引用都能打开、审阅者批了这个 diff」才是证明。
杠杆来自:这个循环你只造一次,之后是系统替你跑它。
Claude 的定时任务(scheduled tasks)就是同一个转向的产品化形态:把反复要做的活儿定义一次,之后系统自己重新进入,不需要你再手敲一条 prompt。
定时只是那个触发器。
真正把一个重复任务变成一个被工程化的 loop 的,是那些检查、那条反馈和那个退出条件。
一个好用的 loop 的解剖
每一个上了生产的 loop,都需要七件东西。
1. 触发器(trigger)
是什么启动了下一轮:一个请求、一张时间表、一个 webhook、一次失败的测试、一份新文档,或者一个评估器(evaluator)的结果。
2. 目标(goal)
一个可度量的、要到达的状态,而不是「持续改进」。
3. State
下一次尝试必须知道的东西——而且不用把整段历史重放一遍。
4. 动作策略(action policy)
agent 可以改什么、调什么、把什么派出去、花多少钱。
5. 证据(evidence)
测试、引用、diff、指标、schema,或者人工评审。
6. 反馈(feedback)
一段紧凑的说明:哪儿失败了,什么必须改。
7. 停止规则(stopping rule)
成功、达到最大尝试次数、预算耗尽、超时、硬错误,或者升级给人。
Loop 是可以叠的
agent loop 干活。
验证 loop 检查这活儿。
事件 loop 在新活儿到来时把系统叫醒。
改进 loop 研究生产环境的 trace,然后去改 harness 本身。
事件 LOOP
└── 验证 LOOP
└── AGENT LOOP
TRACE 改进 LOOP
└── 更新 prompt、工具、策略与评分器(grader)
这就是为什么 loop engineering 比 prompt engineering 大一圈。
一条 prompt 定义的是一次模型调用之内该发生什么。
一个 loop 定义的是这次调用之后系统要做什么。
代价是明摆着的。
每一次重试、每一个评分器、每一个审阅者,都在加延迟和加钱。
当失败的预期代价高于验证的代价时,才加这个 loop。
第三层:Graph Engineering
Graph engineering 问的是另一个问题。
不是「agent 该怎么干活」。
而是「下一步允许跑什么」。
工作变成节点。
被允许的转移变成边。
state 在图里流动。
这个结构可以表达:
- 固定的顺序
- 条件分支
- 并行扇出(fan-out,也就是一次同时叫上好几个帮手)
- 汇合
- 有边界的循环
- 恢复路径
- 人工打断
Graph 工程师真正在定的是什么
节点边界
哪些活儿该放进普通代码、哪些放进一次 LLM 调用、哪些交给专职 agent、哪些必须走人工评审。
State schema
每个节点可以读什么、可以更新什么,以及并行的结果怎么合并。
路由条件
什么样的证据让工作往前走、往回退、横着挪,或者升级上报。
并发
什么可以并行跑,什么必须停下来等汇合。
循环与出口
哪里允许重试、允许几次,以及什么东西让这个循环是安全的。
持久性
在哪里打检查点,以及被打断之后怎么恢复。
什么时候值得为 graph 走这套仪式
当流程里真的含有有意义的分支、并行的专职角色、审批、恢复路径或者带 state 的交接时,才上 graph。
不要只因为工作流有好几步就从 graph 开始。
如果一个够强的 agent 配三个工具就能解决,那 graph 加的是结构,不是价值。
还有另一种失败模式。
团队在还没看懂这活儿之前,就先把工作流形式化了。
结果是一张漂亮的图,把一堆错的假设固化了进去。
先从一个简单的 harness 开始。
去研究真实的 trace。
把那些始终稳定下来的路径,再形式化。
loop 之后的下一步,是把执行的拓扑显式化。
OpenAI 把同一个想法打包成了 Agent Builder:一块看得见的工作流画布,给多 agent 执行配上护栏(guardrail)和评估。
译者注: 这个例子在原文写作之后已经作废。OpenAI 于 2026 年 6 月 3 日把 Agent Builder 与 Evals 平台一起列入弃用,2026 年 11 月 30 日下线(Evals 于 10 月 31 日先转只读),官方建议迁回 Agents SDK。原文这一段的论点依然成立(把执行拓扑显式化),但它的产品例证已经不能当作长期依赖的对象——这恰好印证了下一节的告诫:先攒 trace,再固化路径。
三层在一个真实系统里怎么协同
设想一个「研究 + 发布」的 agent,产出一份讲事实的行业简报。
harness 提供:
- 浏览器和搜索工具
- 来源存储
- 一块写作工作区
- 引用核查
- 权限与审批规则
- 检查点与 trace
graph 控制路线:
研究
↓
起草
↓
事实核查 ── 不过 ──> 研究
│
过
↓
编辑评审 ── 不过 ──> 起草
│
过
↓
人工批准
↓
发布
loop 就住在这条路线里面。
研究节点可以一直搜,搜到来源覆盖够为止。
起草节点可以一直改,改到文风评分器放行为止。
事实核查节点可以把具体哪几句话没有来源支撑返回去,而不是丢一句含糊的「不通过」。
这个嵌套才是重点。
graph 跑在 harness 里面。
loop 跑在 graph 的某些部分里面。
而这些 loop 需要的工具、state 和证据,是 harness 供给的。
三层会重叠,因为真实软件的分层本来就会重叠。
但当系统坏掉的时候,它们仍然给了你三根不同的杠杆。
先诊断,再动架构
| 症状 | 先看哪一层 | 大概率的修法 |
|---|---|---|
| agent 拿不到它需要的数据,或者拿得不安全 | Harness | 更好的工具契约、权限、沙箱和 context 注入 |
| agent 跨会话就把进度忘了 | Harness | 能存住的 state、检查点、进度产物和上下文压缩 |
| 第一版差不多对,但不稳定 | Loop | 外部评分器、确定性测试、可执行的反馈、有限重试 |
| agent 成功了还在跑,或者没拿到证明就停了 | Loop | 基于证据的终止状态 + 认预算的停止规则 |
| 几个专职角色必须按受控的顺序跑 | Graph | 显式的节点、边、路由条件和汇合点 |
| 一次多步失败根本定位不到 | Graph + Harness | 与节点和转移对齐的、带 state 的 trace |
| 流程变得太快,一张固定的图跟不上 | 更简单的 Harness | 让规划继续由模型驱动,推迟 graph 的形式化 |
这张表比争论术语有用得多。
找到那个拥有这次失败的层。先修那一层。
弱 agent 系统背后那些昂贵的错
太早开始画 graph
不要在还没看过一个够强的 agent 真正干过这活儿之前,就把一个想象中的业务流程转成四十个节点。
先攒 trace。再形式化。
让做的人给自己打分
自我评审有用,但它和原来那次尝试共享同一套盲点。
能上确定性检查的地方就上确定性检查。
主观的判断,交给一个上下文隔离的审阅者。
高影响的动作,要求人工批准。
把 loop 定义成「一直试」
无边界的重试不是可靠性。
那是一个漏钱的口子。
每一轮都需要新的证据、一个最大尝试次数,以及一条有名字的升级路径。
把 harness 堆成一个杂货仓库
工具更多,不会自动等于 agent 更好。
工具集一挤,选错的概率就上去。
context 一吵,混乱就上去。
权限一宽,风险就上去。
给 agent 那个能干完这件事的、最小的环境。
把编排的问题算到模型头上
一个更强的模型,修不好过期的 state、坏掉的 API、含糊的工具 schema,或者缺失的退出条件。
在证明模型是问题之前,别急着换模型。
一份上生产前的自检清单
Harness
- 工具是不是窄的、有文档的、可观测的
- state 能不能跨会话存住
- 权限是不是最小的
- 操作者能不能暂停、检查并恢复这次运行
- 每一个重要动作,能不能从 trace 里复原出来
Loop
- 什么证据算成功
- 失败之后返回什么反馈
- 允许重试几次
- 预算耗尽的时候会发生什么
- 哪里必须由人来判断
Graph
- 哪些路径必须是确定性的
- 哪里可以并行
- 什么 state 是共享的
- 汇合点、审批点和恢复路径在哪里
- 哪些循环是合法的,以及它们怎么终止
评估
- 团队能不能重放真实的 trace
- 不同版本能不能拿同一批任务来比
- 一次改进能不能归因到某一处具体的改动
运维
- 成本和延迟有没有在盯
- 失败率能不能按节点、按工具看
- 人工介入有没有被度量
- 生产环境里,任务级的成功率有没有在量
记住这个区别最简单的办法
Harness engineering 让模型能上岗。
Loop engineering 让工作变得可迭代、可验证。
Graph engineering 让复杂的执行变得显式、可控。
没有哪一层能替代另外两层。
一张完美的 graph,救不了一个会丢 state 的 agent。
一个完美的 harness,如果 loop 里既没有证据也没有停止规则,照样烧钱。
一个很强的 loop,一旦分支、并行和审批都藏在东拼西凑的代码里,就会变得没法运维。
可靠的 agent,出现在这三层被一起设计的时候。
以及每一层都只有一个明确职责的时候。
环境 -> HARNESS
反馈 -> LOOP
流程 -> GRAPH
整个框架就这么多。
出处与延伸阅读
- Claude 定时任务
- OpenAI AgentKit(注:Agent Builder 与 Evals 平台将于 2026-11-30 下线)
- OpenAI Agents SDK
- AutoGen GraphFlow
- Building Effective AI Agents(Anthropic)
译自 rari(@0xwhrrari)《The 3 AI Agent Systems Every Builder Must Understand》(原文)。翻译、重排、配图本地化:Yaqin Hei。延伸阅读:站内《Loop Engineering:Karpathy 方法论》《四种 Loop 分别什么时候用》。
Subscribe for updates
Get the latest AI engineering posts delivered to your inbox.