本文目录9 个章节
Harness、Loop 与 Graph 速览
这份实用指南用于区分 3 个经常被混为一谈的架构层。
产生混淆并不奇怪：这 3 个概念都围绕同一个模型展开，都会影响可靠性，内部也都可能出现循环。它们并非同义词，而是对应不同的工程决策；当 Agent 开始操作文件、调用 API、服务用户或接触生产代码时，这一区分就不能省略。
30 秒结论
-
Harness 工程负责搭建模型外围的运行机制。
-
Loop 工程负责设计反复执行、获取反馈的工作循环。
-
Graph 工程把工作流拓扑显式化，包括节点、分支、汇合、状态转移和受控循环。
最简心智模型是：环境 → 反馈 → 流程。
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ H: HARNESS │--> │ L: LOOP │--> │ G: GRAPH │
└──────────────────┘ └──────────────────┘ └──────────────────┘
Environment Feedback Flow-
H — 搭建运行环境，包括工具、记忆、权限、运行时、API 与文件系统。
-
L — 通过思考、行动、检查、反馈和重复来改进工作结果。
-
G — 用节点、分支、汇合、并行与状态控制工作流。
3 个层次对应 3 类职责；混在一起会遮住待解决的设计问题。
这些术语为何在此时重要
原始语言模型无法独自创建文件、维护项目状态、运行测试套件、检查浏览器、执行审批规则或重启失败任务。这些能力来自模型所处的环境。随着 Agent 软件逐渐成熟，一套可辨认的工程栈正在形成：Harness 负责运行模型，Loop 管理重复执行与质量检查，Graph 定义流程中的结构化路径。
这些名称尚未完全标准化。按原文的划分，Agent Harness 已逐渐形成相对明确的含义；Loop Engineering 是较新的从业者术语；Graph Engineering 则是把 Agent 工作流表达为有向图或状态机的实用说法。这套区分能防止流行术语遮住待解决的架构问题。
| 对比问题 | Agent Harness | Loop Engineering | Graph Engineering |
|---|---|---|---|
| 首要关注点 | 运行能力 | 迭代进展与反馈 | 显式控制流 |
| 核心对象 | 模型包装层或运行时 | 有边界、可重复的循环 | 由步骤组成的有向图 |
| 常见构件 | 工具、记忆、沙箱、中间件、权限、追踪 | 触发器、目标、行动、证据、反馈、终止规则 | 节点、边、共享状态、分支、汇合、中断、循环 |
| 解决的故障 | “模型无法安全完成这项工作。” | “Agent 过早停止，或不断重复低质量工作。” | “工作流难以推理或控制。” |
| 适用场景 | 通用 Agent 平台或任务专用运行时 | 通过验证逐步改进的开放式工作 | 决策点已知的复杂多步骤流程 |
| 主要风险 | 臃肿且不透明的运行时 | 无限重试、Token 浪费、奖励投机 | 过度设计的图和脆弱路径 |
Agent Harness 工程
-
LangChain 将 Agent 描述为模型加 Harness。Harness 指模型外部的代码、配置和执行逻辑，包括系统提示词、工具定义、记忆、文件系统、沙箱、模型路由、Handoff、中间件 Hook、上下文压缩、权限、日志与验证接口。
-
OpenAI Agents SDK 从运行时角度描述了同一组核心机制：Runner 调用模型、执行工具调用、处理 Handoff、携带状态，并在运行到达终止条件时停止。
┌─────────────────┐
│ O: ORCHESTRATOR │
└────────┬────────┘
┌────────────────┴────────────────┐
▼ ▼
┌────────────────┐ ┌────────────────┐
│ 1: PLANNING │ │ 2: BACKENDS │
└───────┬────────┘ └───────┬────────┘
▼ ▼
┌────────────────┐ ┌────────────────┐
│ 3: CONTEXT │ │ 4: SUBAGENTS │
└───────┬────────┘ └───────┬────────┘
▼ ▼
┌────────────────┐ ┌────────────────┐
│ 5: MEMORY │ │ 6: SKILLS │
└───────┬────────┘ └───────┬────────┘
▼ ▼
┌────────────────┐ ┌────────────────┐
│ 7: SANDBOXES │ │ 8: HUMAN GATE │
└───────┬────────┘ └───────┬────────┘
└────────────────┬────────────────┘
▼
┌────────────────┐
│ 9: TOOLS │
└───────┬────────┘
▼
┌────────────────┐
│ LLM │
└────────────────┘-
O — 编排 Agent：负责规划、委派和验证。
-
1 — 规划：write_todos 与任务拆解。
-
2 — 后端 + 文件系统：状态、本地、存储与组合。
-
3 — 上下文工程：压缩、隔离与卸载。
-
4 — 子 Agent：隔离上下文、并行执行与异步工作。
-
5 — 记忆：短期任务状态与长期持久化。
-
6 — Skills：可复用工作流，包括 agentskills.io。
-
7 — 沙箱：Modal、Daytona 等隔离执行环境。
-
8 — 人工介入：按工具批准、编辑或拒绝。
-
9 — 工具：自定义函数、MCP Server 与 Harness 内置工具。
-
LLM — 任意支持工具调用的模型。
Harness 这个词能把注意力从单纯比较模型，转向模型实际工作的工程条件。两个团队即使使用同一个基础模型，结果也可能相差很大：一个团队提供清晰的工具、稳定的工作区、受限权限和可观测状态；另一个团队只有含糊的提示词和不可靠的 API 包装。模型能力可能相近，工作条件却完全不同。一套严肃的 Harness 通常包含：
-
上下文注入：指令、检索事实、对话状态、Skills 和任务专用策略。
-
行动入口：API、浏览器、Shell、代码解释器、数据库与 MCP 兼容工具。
-
持久化：文件、检查点、Session、进度日志、Git 历史与长期记忆。
-
执行控制：超时、重试、预算、模型路由、子 Agent 派发与审批门禁。
-
安全与治理：权限、隔离、白名单、密钥处理与人工授权。
-
可观测性：Trace、工具输入输出、状态转移、成本、延迟与评测结果。
┌──────────────────────────── HARNESS ────────────────────────────┐
│ ┌───────────┐ │
│ │ CONTEXT │ │
│ └─────┬─────┘ │
│ ▼ │
│ ┌──────────┐ ┌─────────────┐ ┌──────────┐ │
│ │ CONTROL │ ───────> │ MODEL │ ───────> │ ACTION │ │
│ └──────────┘ └──────┬──────┘ < - - - └──────────┘ │
│ ┌────┴─────┐ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ PERSIST │ │ OBSERVE │ │
│ └────┬─────┘ └────┬─────┘ │
│ └ - - - ▲ - - ┘ │
└──────────────────────────────────────────────────────────────────┘-
CONTEXT — 提示词、记忆、Skills 与对话流入模型。
-
CONTROL — 上下文压缩、编排与 Ralph Loops 约束模型。
-
ACTION — Bash 调用、工具与 MCP 接收模型决策，并把结果送回模型。
-
PERSIST — 模型写入并读取文件系统、Git 与进度文件。
-
OBSERVE — 浏览器截图、测试结果与日志把验证证据送回模型。
模型位于由上下文、控制、行动、持久化和验证组成的 Harness 中。从架构图里移除模型，剩下的大部分组件通常都属于 Harness：工具、数据访问、状态存储、沙箱、中间件、评估器、重试策略和 UI。
Harness 工程发挥价值的场景
长时任务尤其依赖 Harness。原文引用 Anthropic 的多 Session 编程实践，并指出只做上下文压缩还不够。更稳妥的运行机制会准备初始化器、进度文件、Git 历史和增量工作纪律，让每个新 Session 都能恢复已完成内容和剩余任务。当 Agent 缺少能力、无法干净恢复、丢失状态、权限过宽、无法审计，或在不同环境中表现不一致时，应从 Harness 层处理。
Loop 工程
每个使用工具的 Agent 都包含一个小循环：
-
调用模型。
-
检查结果。
-
运行工具。
-
把观察结果送回模型。
-
重复执行，直到系统返回最终答案。
开发者有意识地在这个行为外设计或叠加新循环，就进入了 Loop 工程。Verification Loop 让 Agent 生成产物后运行确定性检查或 Grader；证据不通过时，系统返回明确反馈并重试。Event-driven Loop 在收到定时任务、Webhook 或新文档时唤醒 Agent。Improvement Loop 分析 Trace 与失败样例，修改指令或工具，再测试新版本是否更好。LangChain 在 2026 年将其描述为多层 Loop 的叠加，而不是一条神奇的 while 语句。
一套设计完整的 Loop 包含哪些要素
-
触发器：启动下一轮循环的信号，例如用户请求、定时任务、失败测试、新数据或评估器反馈。
-
目标：需要到达的具体状态，不能只写“持续改进”。
-
状态与记忆：下一轮所需的信息，避免重放全部历史。
-
行动策略：Agent 可以修改、调用、委派或消耗哪些资源。
-
证据：测试、Schema 校验、引用、Diff、指标或人工审查。
-
反馈：简短且可执行地说明证据未通过的原因。
-
终止规则：成功、预算上限、超时、不可恢复错误或转交人工。
┌────────────── AGENT LOOP ──────────────┐
[REQ] ─────────> │ [MODEL] ──── action ────> [TOOLS] │
│ ▲ <─── observation ──────┘ │
│ │ │
│ ▼ │
│ [PR] │
└────┬───────────────────────────────────┘
▼
[GRADER] ───── pass ─────> [DONE]
│
└──── feedback ──────> [MODEL]-
REQ — 文档改进请求。
-
MODEL — 规划并起草修改。
-
TOOLS — 沙箱工具负责 Clone、读取与写入；行动向外发送，观察结果返回。
-
PR — 包含 Diff 与描述的 Pull Request。
-
GRADER — 检查链接是否可访问、CI 是否通过。
-
DONE — 通过后结束；失败则把反馈送回 MODEL。
Loop 工程为何不等同于 Prompt 工程
Prompt 规定模型在单次调用中做什么；Loop 规定这次调用结束后，系统接着做什么。
它定义系统如何观察结果、选择反馈、决定是否继续、保存进度并终止。
Prompt 质量仍然重要，但 Loop 能把一次性指令变成受管理的过程。主要代价是成本和延迟：每增加一个 Grader、Reviewer 或重试，就会多一次模型调用或工具运行。Anthropic 的通用建议是优先使用能满足需求的最简架构，只在性能收益足以抵消复杂度时增加 Agent 机制。只有当失败成本高于验证成本时，才值得增加 Loop。
Graph 工程
Graph 工程追问的是另一个问题：不仅要知道 Agent 在做什么，还要明确下一步允许哪个组件运行。步骤表现为节点，允许的转移表现为边；边可以表示顺序、条件分支、并行扇出、汇合、循环和人工中断。状态沿图流转，使预期控制流可以检查。LangGraph 面向长时运行的有状态 Agent，提供持久执行和人工介入等低层编排能力。AutoGen 的 GraphFlow 文档则用执行图控制 Agent 的运行顺序。Graph 工程需要决定：
-
节点边界：哪些工作交给确定性函数、LLM 调用、专用 Agent 或人工审查。
-
状态 Schema：每个节点可以读写哪些字段，以及并行更新如何合并。
-
路由条件：哪些证据让工作向前、退回、转入其他分支或升级处理。
-
并发：哪些工作可以并行，哪里必须汇合，哪些共享资源需要协调。
-
循环与退出：哪里允许重试、最多重试几次，以及如何保证循环安全。
-
持久性：在哪里建立检查点，中断后如何恢复执行。
工作流 Canvas 能让 Agent、Skills 和相互关系以组合系统的形式接受检查。这里的 Graph 工程指基于图的执行工程，不是知识图谱工程。知识图谱表示数据中的实体和关系；工作流图表示控制与状态转移。
何时值得引入 Graph
当流程包含有意义的分支、并行任务、审批、恢复路径或多个专用 Agent 时，Graph 才有明显价值。如果工作只是“给一个 Agent 3 个工具，让它自行处理”，Graph 的帮助有限。Graph 便于调试，也可能过早固定假设。若模型必须动态生成计划，把所有可能路径都塞进静态图反而会让系统更脆弱。
3 个层次如何在实际系统中协作
以一个负责生成事实型行业简报的研究与发布 Agent 为例。
| 层次 | 在研究与发布系统中的职责 |
|---|---|
| Harness | 提供浏览器、搜索工具、文档工作区、引用存储、模型路由、密钥、权限、Trace 日志和审批界面。 |
| Graph | 让任务依次经过范围界定 → 并行研究 → 来源筛选 → 综合 → 起草 → 法务审查 → 发布，并在发布前设置人工门禁。 |
| Loops | 来源覆盖不足时重新检索；引用校验失败时退回草稿修改；市场变化时按计划重新运行。 |
Graph 运行在 Harness 内部；一个或多个 Loop 位于 Graph 之中；Harness 为这些 Loop 提供状态、工具和评估器。软件层会重叠，所以这些类别也会重叠，但系统出错时，每一层都对应不同的调整手段。
根据故障选择工程层
| 故障现象 | 先检查 | 可能的修复 |
|---|---|---|
| Agent 无法安全访问所需数据或工具。 | Harness | 工具契约、权限、沙箱、上下文注入。 |
| Agent 在跨 Session 工作中忘记进度。 | Harness | 持久状态、检查点、进度产物、上下文压缩。 |
| 首次结果接近目标但不稳定。 | Loop | 外部 Grader、确定性测试、反馈、有界重试。 |
| Agent 成功后仍继续运行，或未拿到证据就停止。 | Loop | 基于证据的终止状态、考虑预算的停止规则。 |
| 多个专用 Agent 必须按受控顺序运行。 | Graph | 显式节点、边、路由条件与汇合。 |
| 多步骤流程中的故障难以定位。 | Graph + Harness | 与图节点和状态转移对齐的有状态 Trace。 |
| 工作流变化太快，不适合固定图。 | 简化 Harness | 保留模型驱动控制，推迟 Graph 形式化。 |
Agent 架构常见错误及其代价
尚未理解工作就先画 Graph
有些团队还没观察高能力 Agent 如何解决问题，就把业务流程拆成几十个节点。先从较简单 Harness 的 Trace 中找稳定路径，再将这些路径形式化。
缺少防护地让同一模型同时生成和评分
Self-review 有帮助，也会继承同一组盲点。能用确定性检查时优先使用；Reviewer 应采用分离的上下文；高影响操作需要人工批准。
把“继续尝试”当成 Loop 规范
无界重试会持续消耗成本。每个 Loop 都需要可测目标、新证据、最大尝试次数和明确的升级路径。
把 Harness 当成杂物箱
工具和记忆并非越多越好。拥挤的工具集会增加选择错误，嘈杂的上下文会增加混乱，过宽权限会增加风险。
把编排故障归咎于模型
模型无法可靠弥补陈旧状态、含糊的工具 Schema、故障 API 或缺失的退出条件。哪一层拥有故障，就改哪一层。
生产就绪设计清单
-
Harness：工具是否收敛、文档齐全且可观测？状态是否持久？权限是否遵循最小授权？运维人员能否暂停、检查并恢复运行？
-
Loop：什么证据可以证明成功？失败后返回什么反馈？最多允许几次重试？预算耗尽时如何处理？
-
Graph：哪些路径必须保持确定性？哪里可以并行？哪些状态需要共享？人工门禁与恢复路线放在哪里？
-
Evaluation：团队能否 Replay 真实 Trace、比较版本，并把改进归因到某项具体变化，而不是凭直觉判断？
-
Operations：生产环境是否监控成本、延迟、失败率、人工介入率与任务级成功率？
记住三者区别的最简方法
Harness 工程给模型搭建可以运行的环境；Loop 工程让工作可迭代、可验证、可恢复；Graph 工程让复杂执行路径显式且可控。这 3 个层次不能互相替代。Harness 没保存状态，再漂亮的 Graph 也无法恢复；Harness 能力再完整，没有证据和终止规则仍会浪费时间与成本；精心设计的 Loop 如果把分支、并行和审批埋在临时代码里，照样难以运维。团队需要同时设计 3 个层次，并明确每一层负责解决哪类故障。
资料来源与延伸阅读
本文实际使用的 5 个交叉核验来源
-
The Anatomy of an Agent Harness — 定义模型外围的 Harness，并介绍文件系统、沙箱、记忆、编排和验证。
-
Agents SDK | OpenAI API — 说明 SDK 中的 Agent、Runner、工具、Handoff、Guardrail、Session、Tracing 与 Result。
-
GraphFlow (Workflows) — AutoGen — 说明结构化多 Agent 执行图、顺序、分支与循环。
-
The Art of Loop Engineering — 介绍 Agent 基础 Loop，以及如何在其外围叠加新的 Loop。
-
Building Effective AI Agents — 建议从能工作的最简架构开始，只在复杂度产生可测收益时再增加机制。
REFERENCES