个语言模型，每次 API 调用都是独立事件。不记得上一轮说了什么，不知道三分钟前调过什么工具，更不会在进程崩溃后从断点恢复。它没有真正的主动性——本质上是被一个 while 循环推着走的。

这个 while 循环，加上它周围的一整套基础设施，就是 Harness。

OpenAI 在 2026 年 2 月正式把它命名为 "Harness Engineering"，并定义为独立学科。在那之前，Codex 的团队已经通过 AI 生成了 100 万行生产代码——零手写——靠的不只是模型有多强，很大程度上是 Harness 足够可靠。

公式很简单：Agent = Model + Harness。但做起来不简单。

---

为什么 Demo 跑通了，生产环境一塌糊涂

先看一个真实数字：一个 10 步的工作流，每步 90% 成功率，整条链路跑通的概率只有 35%。提到 95%，也只有 60%。

Agent 不是那种"要么对要么错"的系统。它在每一步都面临多个决策分支（该调哪个工具、参数填什么、结果可信不可信、要不要重试），每个分支都在累积不确定性。单步的错误率看似可控，乘起来就是灾难。

Demo 看起来好，是因为你盯着它跑。出了问题你手动纠正、重启上下文、换个问法重来。没有人盯着的时候，它需要一个自动化的"你"——一个知道什么时候重试、什么时候放弃、什么时候换方案的运行时系统。

这就是 Harness 要解决的问题。

2026 年的一条核心结论来自 LangChain 自己的实践：同一个模型，Harness 改进后，Terminal Bench 排名从第 30 跳到第 5，分数从 52.8% 提到 66.5% 。Harness 设计的差异可以拉开 40 分的任务完成率差距，模型没变。

---

架构拆解：一个 Harness 由哪些层组成

2026 年 4 月的 arXiv 论文《Architectural Design Decisions in Harnesses》（2604.18071）对 70 个开源 Agent 系统做了实证分析，结论是 60% 的系统采用 Agent Loop 作为核心执行模式。但 Loop 只是骨架，真正的差异在上面长出的五层结构。

第一层：推理-行动循环（ReAct）

ReAct 循环是 Harness 的心脏。它的结构简单到只有四步循环：

这个循环源自 Yao 等人在 2022 年发表的 ReAct 论文（arXiv:2210.03629）。它的核心洞察是：让模型在推理（Thought）和行动（Action）之间交替，而不是先想完再行动或先行动完再想。每一步的行动结果反馈回上下文，成为下一步推理的输入。

ReAct 解决了纯 CoT（Chain-of-Thought）的两个致命问题：一是推理过程与外部世界隔离，错误假设没有机会被纠正；二是模型倾向于"脑补"事实而非查询验证。这种交替执行方式强制模型用真实数据替代想象。

在 2026 年的生产实践中，ReAct 是大多数 Harness 框架的默认循环模式。LangGraph、OpenAI Agents SDK——底层都是这个四步循环。

第二层：工具调用协议

工具调用有三个关键设计决策，每个都影响 Agent 的可靠性。

工具数量：并非越多越好。 Vercel 在 2026 年做了一个著名的实验：将 Text-to-SQL Agent 从 15-18 个专用工具砍到 2 个（bash + SQL 执行），结果成功率从 80% 跳到 100%，速度快了 3.5 倍，token 消耗减少 37%。

原因很直接：更多工具意味着更多决策分支，模型在每个分支上分配注意力，每一个分支都有不确定性。模型在"选哪个工具"上花的算力，挤占了"怎么解决问题"的算力。

Schema 设计：写给初级开发者的文档。 Anthropic 在 "Building Effective Agents"（2024 年 12 月）中提出了 ACI（Agent-Computer Interface）原则——对待工具描述的态度，应该跟对待用户界面设计一样认真。

具体做法：包含使用示例、标注边界条件、用强制格式避免歧义（比如绝对路径而非相对路径）、清晰区分相似工具（"用 search_code 查代码，用 search_docs 查文档，两不混用"）。

协议标准化：MCP 的 N+M 收敛。 在 MCP（Model Context Protocol，Anthropic 2024 年 11 月发布）之前，N 个 Agent 对接 M 个工具是 N×M 的集成问题。MCP 把它降为 N+M——每个 Agent 说 MCP，每个工具暴露 MCP Server，任意组合即插即用。到 2026 年 3 月，MCP SDK 月下载量超过 9,700 万次，10,000+ 公共 MCP Server 在生产中运行（spec.modelcontextprotocol.io 数据）。

A2A（Google 2025 年 4 月发布）补充了 Agent 间的通信协议。两个协议一起，构成了 2026 年 Agent 生态的基础设施层。

第三层：上下文管理

LLM 的上下文窗口在快速增长，2026 年主流模型已经普遍支持 100 万 token 上下文。但更长不等于更好。上下文越长，模型越容易在噪声中迷失，token 成本线性增长，Prefix Caching 命中率下降。

上下文管理的核心策略是分层：

1静态提示词放前面：系统身份、通用行为规则、核心工具 Schema——这些几乎不变的内容固定在上下文开头。Anthropic 的 Context Engineering 文章（2025 年 9 月）指出，静态内容在前、动态内容在后可以最大化 Prefix Caching 的收益，缓存命中时只支付新增 token 的费用。2会话历史做压缩：不是保留全部对话，而是每 N 轮做一次摘要压缩。压缩策略的选择直接影响 Agent 的"记忆质量"——太激进丢失关键上下文，太保守等于没压缩。3工具输出做卸载：工具返回的大量数据（如搜索结果、文件内容）不在上下文里逐字保留，而是存入结构化存储（向量数据库、SQLite、文件系统），仅在需要时检索。Claude Code 和 Manus 都采用了这种"上下文与存储分离"的模式。

第四层：状态持久化

Agent 最脆弱的时候发生在崩溃之后，而非运行之中。

Harness 的标准做法是事件溯源（Event Sourcing）——每个事件（用户消息、工具调用、工具结果、压缩事件）以 JSONL 格式追加写入磁盘，一行一条，立即落盘。进程在第 47 行崩溃，第 47 行之前的状态就是安全的。重启后从第 47 行恢复（不是重新开始，是接着跑）。

这个模式在 Anthropic 的 "Effective Harnesses" 文章（2025 年 11 月）中以 Ralph Loop 的名字被形式化。Ralph Loop 的核心是代理边界跨越（Context Boundary Crossing）：当上下文窗口接近极限时，Stop Hook 拦截模型退出意图，从文件系统读取当前状态，将原始任务重新注入一个干净的上下文窗口，然后继续执行。

状态存在于磁盘上，上下文窗口只是工作缓存。

Manus 在 6 个月内重写了 Harness 5 次。一个反复出现的主题是 ：状态持久化的设计，是 Harness 里容易被低估、也最需要迭代的部分之一。

第五层：错误恢复

Agent 系统的错误不同于传统软件。大多数传统软件的错误是"二元的"——请求成功或失败，返回 200 或 500。Agent 的错误更复杂：200 OK 可以返回一个完全错误的计算结果；模型可以在连续 5 步正确后突然天马行空。

生产环境的错误恢复采用分层策略，从内到外：

1重试（Retry）：指数退避 + 随机抖动。有效减少 60-80% 的重试风暴。适用于网络超时、API 限流等瞬时故障。2降级（Fallback）：识别到当前模型不可用或输出质量过低，切换到备用模型。降级链：主力模型 → 备选模型 → 本地小模型 → 缓存结果。3熔断（Circuit Breaker）：某种工具或服务连续 5 次失败，熔断器打开，暂停调用 30-60 秒，再半开探测。保护上游依赖不被雪崩拖垮。4重规划（Re-plan）：工具返回的结果与当前计划冲突，回到 Planner 生成新计划。不盲目执行错误的路线。5人工升级（Human-in-the-loop）：以上所有自动恢复耗尽后，暂停 Agent，通知人类操作员决策。这是最后的安全网。

---

从零构建：500 行 Python 搭一个生产骨架

目标不是做一个通用框架。是做一个能跑的参考实现——你可以读完直接抄、改、扩展。所有代码用 Python 写，依赖只有标准库 + OpenAI SDK。

完整的 Harness 包含六个模块：

1核心循环 — Agent 运行的主 while 循环2工具注册表 — 工具的定义、验证、分发3上下文管理 — 提示词组装与压缩4状态持久化 — JSONL 追加写入，崩溃恢复5权限门控 — 工具调用前后的安全检查6错误恢复 — 指数退避重试 + 熔断器