--- title: "超级AI背后的秘密武器：Agent Harness深度解析" source: wechat url: https://mp.weixin.qq.com/s/Y0kRzN1DbX7My3cz4eVR1Q ingest_date: 2026-07-04 vxc: 56 stars: 4 sha256: 1b22d7c88b2fc155ec9588fef2fca94006f983b387e9af59a049b14df653de25 --- # 超级AI背后的秘密武器：Agent Harness深度解析 **来源**: Unknown **发布日期**: 2026-04-15 **原文链接**: https://mp.weixin.qq.com/s/Y0kRzN1DbX7My3cz4eVR1Q --- # 你的 AI 为什么总在演示时掉链子？ 你做过一个聊天机器人。也许还接上了几个工具，跑个 ReAct 循环。演示的时候一切正常。 然后你尝试把它做成生产级产品，轮子就开始掉了：模型三步之后就忘了自己干了什么，工具调用悄无声息地失败，上下文窗口里塞满了垃圾数据。 问题不在你的模型。问题在模型周围的一切。 LangChain 证明了这一点：他们只改了 LLM 外围的基础设施（同样的模型，同样的参数），排名就从 TerminalBench 2.0 的前 30 名之外一路飙升到第 5 名。还有一个研究项目，让 LLM 自己优化基础设施，最终达到 76.4% 的通过率，超过了手工设计的系统。 这套基础设施，现在有个专门的名字： Agent Harness 。 ## 什么是 Agent Harness？ 这个术语是 2026 年初正式提出的，但概念早就存在了。Harness 是包裹 LLM 的完整软件基础设施：编排循环、工具、记忆、上下文管理、状态持久化、错误处理和防护机制。 Anthropic 的 Claude Code 文档说得很直白：SDK 就是"驱动 Claude Code 的 Agent Harness"。OpenAI 的 Codex 团队用同样的框架，明确把"Agent"和"Harness"等同起来，指的都是让 LLM 有用的非模型基础设施。 我很喜欢 LangChain 的 Vivek Trivedy 那句经典公式： "如果你不是模型，那你就是 Harness。" 这里有个容易混淆的区别。"Agent"是涌现出来的行为——那个有目标导向、会使用工具、能自我纠正的实体，是用户实际交互的对象。Harness 是产生这种行为背后的 machinery。当有人说"我做了个 Agent"，他们的意思是"我做了个 Harness，然后接了个模型"。 Beren Millidge 在 2023 年的文章里把这个类比讲得更精确。他把原始 LLM 比作一台只有 CPU、没有内存、没有硬盘、没有输入输出设备的计算机。上下文窗口充当内存（快但容量有限），外部数据库充当硬盘存储（容量大但慢），工具集成充当设备驱动。 Harness 就是操作系统 。 正如 Millidge 写的："我们重新发明了冯·诺依曼架构"，因为这对任何计算系统来说都是自然的抽象。 ## 工程三层论 围绕着模型，有三个同心圆式的工程层次： - • 提示工程 ：雕琢模型收到的指令 - • 上下文工程 ：管理模型能看到什么、什么时候看到 - • Harness 工程 ：涵盖以上两者，再加上整个应用基础设施——工具编排、状态持久化、错误恢复、验证循环、安全执行和生命周期管理 Harness 不是提示的包装器。它是让自主 Agent 行为成为可能的完整系统。 ## 生产级 Harness 的 11 个核心组件 综合 Anthropic、OpenAI、LangChain 和更广泛的实践社区，一个生产级的 Agent Harness 有 12 个不同的组件。 ### 1. 编排循环 这是心脏跳动。它实现了思想 - 行动 - 观察（TAO）循环，也叫 ReAct 循环。循环跑起来：组装提示 → 调用 LLM → 解析输出 → 执行工具调用 → 把结果喂回去 → 重复直到完成。 机械上，它通常只是个 while 循环。复杂性在于循环管理的一切，而不是循环本身。Anthropic 把他们的运行时描述为"傻瓜循环"——所有智能都住在模型里，Harness 只是管理回合。 生活化比喻 ：编排循环就像厨师炒菜的过程——看一眼菜谱（提示），切一刀菜（行动），尝一口味道（观察），再调整火候，重复直到出锅。循环本身简单，难的是管理好每一道工序。 ### 2. 工具 工具是 Agent 的手。它们被定义为模式（名称、描述、参数类型），注入 LLM 的上下文中，让模型知道有什么可用。工具层处理注册、模式验证、参数提取、沙箱执行、结果捕获，以及把结果格式化回 LLM 可读的观察。 Claude Code 提供六大类工具：文件操作、搜索、执行、网页访问、代码智能和子 Agent 生成。OpenAI 的 Agents SDK 支持函数工具、托管工具（网页搜索、代码解释器、文件搜索）和 MCP 服务器工具。 生活化比喻 ：工具就像瑞士军刀上的各个刀片——每个都有特定用途，用的时候抽出来，用完收回去。Agent 知道什么时候该用哪把刀，但前提是这些刀得摆在它够得着的地方。 ### 3. 记忆 记忆在多时间尺度上运作。短期记忆是单次会话中的对话历史。长期记忆跨会话持久化：Anthropic 使用 CLAUDE.md 项目文件和自动生成的 MEMORY.md 文件；LangGraph 使用命名空间组织的 JSON Store；OpenAI 支持基于 SQLite 或 Redis 的会话。 Claude Code 实现了三层层级：轻量级索引（每条约 150 字符，始终加载）、详细主题文件（按需拉取）、原始转录（仅通过搜索访问）。一个关键设计原则：Agent 把自己的记忆当作"提示"，在行动前会对照实际状态验证。 生活化比喻 ：记忆系统就像人的大脑——短期记忆是工作记忆，记住刚才说了什么；长期记忆是笔记本，记下重要决策和待办事项；而原始对话记录就像录音笔，需要时再回去翻。 ### 4. 上下文管理 这里是很多 Agent 悄无声息失败的地方。核心问题是 上下文腐烂 ：当关键内容掉进窗口中间位置时，模型性能下降超过 30%（Chroma 研究证实了斯坦福"Lost in the Middle"的发现）。即使是百万 token 窗口，随着上下文增长，指令遵循也会退化。 生产级策略包括： - • 压缩 ：接近限制时总结对话历史（Claude Code 保留架构决策和未解决的 bug，丢弃冗余的工具输出） - • 观察掩码 ：JetBrains 的 Junie 隐藏旧工具输出，但保持工具调用可见 - • 即时检索 ：维护轻量级标识符，动态加载数据（Claude Code 用 grep、glob、head、tail 而不是加载完整文件） - • 子 Agent 委托 ：每个子 Agent 广泛探索，但只返回 1000-2000 token 的浓缩摘要 Anthropic 的上下文工程指南说得很清楚：目标是最小化高信号 token 的集合，最大化期望结果的概率。 生活化比喻 ：上下文管理就像整理办公桌——重要的文件放在手边（窗口两端），用过的文件收进抽屉（压缩），需要时再查（即时检索），太乱的桌面定期清理（掩码）。桌子就那么大，关键是要让最重要的东西永远在最顺手的位置。 ### 5. 提示构建 这一步组装模型在每一步实际看到的内容。它是分层的：系统提示、工具定义、记忆文件、对话历史，以及当前用户消息。 OpenAI 的 Codex 使用严格的优先级栈：服务器控制的系统消息（最高优先级）、工具定义、开发者指令、用户指令（级联 AGENTS.md 文件，32 KiB 限制），然后是对话历史。 生活化比喻 ：提示构建就像给领导准备汇报材料——最上面是核心结论（系统提示），下面是数据支撑（工具定义），再下面是背景资料（记忆文件），最后是之前的讨论记录（对话历史）。领导时间有限，所以要把最重要的放最上面。 ### 6. 输出解析 现代 Harness 依赖原生工具调用——模型返回结构化的 tool_calls 对象，而不是需要解析的自由文本。Harness 检查：有工具调用吗？执行它们并循环。没有工具调用？那就是最终答案。 对于结构化输出，OpenAI 和 LangChain 都支持通过 Pydantic 模型的模式约束响应。遗留方法如 RetryWithErrorOutputParser（把原始提示、失败的完成和解析错误一起喂回模型）仍然可用于边缘情况。 生活化比喻 ：输出解析就像海关检查——结构化通关（原生工具调用）直接放行，自由文本得开箱检查（解析），有问题的打回去重来（重试解析）。 ### 7. 状态管理 LangGraph 将状态建模为类型字典，流经图节点，reducer 合并更新。检查点发生在超步边界，支持中断后恢复和时间旅行调试。OpenAI 提供四种互斥策略：应用内存、SDK 会话、服务器端对话 API，或轻量级 previous_response_id 链。Claude Code 采用不同方法：git 提交作为检查点，进度文件作为结构化草稿。 生活化比喻 ：状态管理就像游戏存档——可以随时读档（恢复），回退到之前的关卡（时间旅行），或者用快速存档链（response_id）继续玩。 ### 8. 错误处理 这里有个关键数字：10 步流程，每步 99% 成功率，端到端成功率只有约 90.4%。错误会快速累积。 LangGraph 区分四种错误类型：瞬态错误（指数退避重试）、LLM 可恢复错误（作为 ToolMessage 返回让模型调整）、用户可修复错误（中断等待人工输入）、意外错误（冒泡上报用于调试）。Anthropic 在工具处理器内捕获失败，作为错误结果返回以保持循环运行。Stripe 的生产 Harness 将重试次数上限设为两次。 生活化比喻 ：错误处理就像餐厅服务——上菜慢了等一等（瞬态重试），客人说太咸了换一道（LLM 可恢复），客人对食材过敏等他自己决定（用户可修复），厨房着火直接找店长（意外上报）。 ### 9. 防护机制和安全 OpenAI 的 SDK 实现三个层级：输入防护（在第一个 Agent 上运行）、输出防护（在最终输出上运行）、工具防护（在每次工具调用时运行）。"触发线"机制在被触发时立即停止 Agent。 Anthropic 在架构上分离权限执行和模型推理。模型决定尝试什么，工具系统决定允许什么。Claude Code 独立控制约 40 个离散工具能力，分三个阶段：项目加载时建立信任、每次工具调用前检查权限、高风险操作需要显式用户确认。 生活化比喻 ：防护机制就像公司门禁——员工卡能刷开哪些门（工具权限），能带什么东西进出（输入输出防护），危险操作需要领导审批（用户确认）。 ### 10. 验证循环 这是区分玩具演示和生产级 Agent 的关键。Anthropic 推荐三种方法：基于规则的反馈（测试、linter、类型检查器）、视觉反馈（通过 Playwright 截图用于 UI 任务）、LLM 作为评委（单独子 Agent 评估输出）。 Claude Code 创始人 Boris Cherny 指出，给模型一种验证自己工作的方式可以将质量提高 2 到 3 倍。 生活化比喻 ：验证循环就像考试交卷前的检查——用计算器验算（规则验证），看看卷面整洁度（视觉验证），或者让同学帮忙看一下（LLM 评委）。 ### 11. 子 Agent 编排 Claude Code 支持三种执行模型：Fork（父上下文的字节级复制）、Teammate（独立终端窗口，基于文件的邮箱通信）、Worktree（自己的 git 工作树，每个 Agent 独立分支）。OpenAI 的 SDK 支持 Agent 即工具（专家处理有界子任务）和交接（专家接管完全控制）。LangGraph 将子 Agent 实现为嵌套状态图。 生活化比喻 ：子 Agent 就像外包团队——Fork 是把完整项目资料复制一份给外包，Teammate 是同一办公室不同工位，Worktree 是外包在自己的场地独立开发。 ## 循环运转：一步步 walkthrough 现在你知道组件了，让我们追踪它们如何在单个循环中协作。 第 1 步（提示组装） ：Harness 构建完整输入——系统提示 + 工具模式 + 记忆文件 + 对话历史 + 当前用户消息。重要上下文被放置在提示的开头和结尾（"Lost in the Middle"发现）。 第 2 步（LLM 推理） ：组装好的提示发送到模型 API。模型生成输出 token：文本、工具调用请求，或两者。 第 3 步（输出分类） ：如果模型产生文本且没有工具调用，循环结束。如果有工具调用，继续执行。如果请求交接，更新当前 Agent 并重启。 第 4 步（工具执行） ：对于每个工具调用，Harness 验证参数、检查权限、在沙箱环境中执行、捕获结果。只读操作可以并发运行；变更操作串行运行。 第 5 步（结果打包） ：工具结果格式化为 LLM 可读的消息。错误被捕获并作为错误结果返回，让模型可以自我纠正。 第 6 步（上下文更新） ：结果附加到对话历史。如果接近上下文窗口限制，Harness 触发压缩。 第 7 步（循环） ：回到第 1 步。重复直到终止。 终止条件是多层的：模型产生无工具调用的响应、超过最大回合限制、token 预算耗尽、防护触发线触发、用户中断，或返回安全拒绝。简单问题可能只需 1-2 回合。复杂重构任务可以在多个回合中链式调用数十个工具。 对于跨越多个上下文窗口的长运行任务，Anthropic 开发了两阶段"Ralph Loop"模式：初始化 Agent 设置环境（初始化脚本、进度文件、功能列表、初始 git 提交），然后每个后续会话中的编码 Agent 读取 git 日志和进度文件定位自己，选择优先级最高的未完成功能，完成它，提交，并写入摘要。 文件系统提供了跨上下文窗口的连续性 。 ## 真实框架如何实现这个模式 Anthropic 的 Claude Agent SDK 通过单个 query() 函数暴露 Harness，创建 Agent 循环并返回流式消息的异步迭代器。运行时是"傻瓜循环"，所有智能都在模型里。Claude Code 使用 Gather-Act-Verify 循环：收集上下文（搜索文件、阅读代码）→ 采取行动（编辑文件、运行命令）→ 验证结果（运行测试、检查输出）→ 重复。 OpenAI 的 Agents SDK 通过 Runner 类实现 Harness，有三种模式：异步、同步和流式。SDK 是"代码优先"：工作流逻辑用原生 Python 表达，而不是图 DSL。Codex Harness 扩展为三层架构：Codex Core（Agent 代码 + 运行时）、应用服务器（双向 JSON-RPC API）、客户端界面（CLI、VS Code、Web 应用）。所有界面共享同一个 Harness，这就是为什么"Codex 模型在 Codex 界面上感觉比通用聊天窗口更好"。 LangGraph 将 Harness 建模为显式状态图。两个节点（llm_call 和 tool_node）通过条件边连接：如果有工具调用，路由到 tool_node；如果没有，路由到 END。LangGraph 从 LangChain 的 AgentExecutor 演变而来，后者在 v0.2 被弃用，因为它难以扩展且不支持多 Agent。LangChain 的 Deep Agents 明确使用"Agent Harness"术语：内置工具、规划（write_todos 工具）、用于上下文管理的文件系统、子 Agent 生成和持久化记忆。 CrewAI 实现基于角色的多 Agent 架构：Agent（围绕 LLM 的 Harness，由角色、目标、背景和工具定义）、Task（工作单元）、Crew（Agent 集合）。CrewAI 的 Flows 层添加"确定性骨干网，智能放在需要的地方"，管理路由和验证，而 Crew 处理自主协作。 AutoGen（演变为 Microsoft Agent Framework）开创了对话驱动的编排。它的三层架构（Core、AgentChat、Extensions）支持五种编排模式：顺序、并发（扇出/扇入）、群聊、交接和磁控（管理 Agent 维护动态任务分类账协调专家）。 ## 脚手架比喻 脚手架比喻不是装饰性的。它是精确的。建筑脚手架是临时基础设施，让工人能建造他们 otherwise 够不到的结构。它不做施工。但没有它，工人够不到上层。 关键洞察： 建筑完成时脚手架会被拆除 。随着模型改进，Harness 复杂性应该降低。Manus 在六个月内重建了五次，每次重构都移除复杂性。复杂的工具定义变成了通用 shell 执行。"管理 Agent"变成了简单的结构化交接。 这指向共同进化原则：模型现在用特定的 Harness 进行后训练。Claude Code 的模型学会了使用它被训练的具体 Harness。改变工具实现可能会降低性能，因为这种紧密耦合。 "未来证明测试"用于 Harness 设计：如果性能随着更强大模型扩展而提升，且不增加 Harness 复杂性，设计就是合理的。 ## 定义每个 Harness 的七个决策 每个 Harness 架构师面临七个选择： ### 1. 单 Agent vs. 多 Agent Anthropic 和 OpenAI 都说：先最大化单个 Agent。多 Agent 系统增加开销（路由的额外 LLM 调用、交接时的上下文丢失）。只有当工具过载超过约 10 个重叠工具，或存在明显分离的任务域时才拆分。 ### 2. ReAct vs. 计划 - 执行 ReAct 在每一步交错推理和行动（灵活但每步成本更高）。计划 - 执行将规划与执行分离。LLMCompiler 报告比顺序 ReAct 快 3.6 倍。 ### 3. 上下文窗口管理策略 五种生产方法：基于时间的清除、对话总结、观察掩码、结构化笔记、子 Agent 委托。ACON 研究显示，通过优先处理推理轨迹而非原始工具输出，token 减少 26% 至 54%，同时保持 95% 以上的准确率。 ### 4. 验证循环设计 计算验证（测试、linter）提供确定性基础真值。推理验证（LLM 作为评委）捕捉语义问题但增加延迟。Martin Fowler 的 Thoughtworks 团队将此框架化为引导者（前馈，行动前引导）与传感器（反馈，行动后观察）。 ### 5. 权限和安全架构 宽松（快但危险，自动批准大多数操作）vs. 限制（安全但慢，每个操作需要批准）。选择取决于部署上下文。 ### 6. 工具范围策略 更多工具通常意味着更差性能。Vercel 从 v0 移除了 80% 的工具，得到更好结果。Claude Code 通过延迟加载实现 95% 上下文减少。原则：暴露当前步骤所需的最小工具集。 ### 7. Harness 厚度 多少逻辑住在 Harness 里 vs. 模型里。Anthropic 押注薄 Harness 和模型改进。基于图的框架押注显式控制。Anthropic 定期从 Claude Code 的 Harness 中删除规划步骤，因为新模型版本内化了这种能力。 ## Harness 才是产品 两个使用相同模型的产品，仅基于 Harness 设计就可以有巨大性能差异。TerminalBench 证据很明确：只改变 Harness 就让 Agent 移动了 20 多个排名位置。 Harness 不是已解决的问题，也不是商品层。它是艰难工程所在的地方：把上下文管理为稀缺资源、设计在失败累积前捕获它们的验证循环、构建提供连续性而不产生幻觉的记忆系统，以及在构建多少脚手架与留给模型多少之间做出架构赌注。 随着模型改进，这个领域正朝着更薄的 Harness 发展。但 Harness 本身不会消失。即使是最有能力的模型，也需要东西来管理它的上下文窗口、执行工具调用、持久化状态，以及验证工作。 下次你的 Agent 失败时，不要怪模型。看看 Harness。