个语言模型每次 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 只是骨架真正的差异在上面长出的五层结构。第一层推理-行动循环ReActReAct 循环是 Harness 的心脏。它的结构简单到只有四步循环这个循环源自 Yao 等人在 2022 年发表的 ReAct 论文arXiv:2210.03629。它的核心洞察是让模型在推理Thought和行动Action之间交替而不是先想完再行动或先行动完再想。每一步的行动结果反馈回上下文成为下一步推理的输入。ReAct 解决了纯 CoTChain-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 Agents2024 年 12 月中提出了 ACIAgent-Computer Interface原则——对待工具描述的态度应该跟对待用户界面设计一样认真。具体做法包含使用示例、标注边界条件、用强制格式避免歧义比如绝对路径而非相对路径、清晰区分相似工具用 search_code 查代码用 search_docs 查文档两不混用。协议标准化MCP 的 NM 收敛。 在 MCPModel Context ProtocolAnthropic 2024 年 11 月发布之前N 个 Agent 对接 M 个工具是 N×M 的集成问题。MCP 把它降为 NM——每个 Agent 说 MCP每个工具暴露 MCP Server任意组合即插即用。到 2026 年 3 月MCP SDK 月下载量超过 9,700 万次10,000 公共 MCP Server 在生产中运行spec.modelcontextprotocol.io数据。A2AGoogle 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错误恢复— 指数退避重试 熔断器
Agent Harness 工程核心架构拆解与 300 行代码实现
发布时间：2026/7/27 3:11:33
个语言模型每次 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 只是骨架真正的差异在上面长出的五层结构。第一层推理-行动循环ReActReAct 循环是 Harness 的心脏。它的结构简单到只有四步循环这个循环源自 Yao 等人在 2022 年发表的 ReAct 论文arXiv:2210.03629。它的核心洞察是让模型在推理Thought和行动Action之间交替而不是先想完再行动或先行动完再想。每一步的行动结果反馈回上下文成为下一步推理的输入。ReAct 解决了纯 CoTChain-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 Agents2024 年 12 月中提出了 ACIAgent-Computer Interface原则——对待工具描述的态度应该跟对待用户界面设计一样认真。具体做法包含使用示例、标注边界条件、用强制格式避免歧义比如绝对路径而非相对路径、清晰区分相似工具用 search_code 查代码用 search_docs 查文档两不混用。协议标准化MCP 的 NM 收敛。 在 MCPModel Context ProtocolAnthropic 2024 年 11 月发布之前N 个 Agent 对接 M 个工具是 N×M 的集成问题。MCP 把它降为 NM——每个 Agent 说 MCP每个工具暴露 MCP Server任意组合即插即用。到 2026 年 3 月MCP SDK 月下载量超过 9,700 万次10,000 公共 MCP Server 在生产中运行spec.modelcontextprotocol.io数据。A2AGoogle 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错误恢复— 指数退避重试 熔断器
