问题不在模型
你搭过一个 Agent 原型：接了 ReAct 循环，挂了几件工具，演示效果不错。但当你把它推向生产环境，问题接踵而至——模型记不住三步前的操作，工具调用静默失败，上下文窗口被垃圾数据填满。
问题不在模型权重，而在模型周围的一切。
LangChain 有一个典型案例：只调整了包裹 LLM 的基础设施，模型本身一字未动，TerminalBench 2.0 排名从 30 名开外跃升至第 5。另一项研究让 LLM 自行优化基础设施，通过率达到 76.4%，超过人工设计的系统。
这套基础设施，在 2026 年初正式得名：Agent Harness。
什么是 Agent Harness
Anthropic 在 Claude Code 文档中直白地写道：SDK 就是「驱动 Claude Code 的 agent harness」。OpenAI Codex 团队也采用同一框架，将「agent」和「harness」视为等价概念——专指让 LLM 变得有用的非模型基础设施。
LangChain 的 Vivek Trivedi 给出了一个清晰的边界：如果你不是模型本身，你就是 harness。
这里有一个常见的概念混淆需要澄清。「Agent」是涌现出来的行为——用户交互的那个有目标、会用工具、能自我纠正的实体。Harness 是产生这种行为的机器。当有人说「我做了一个 agent」，他们实际上做了一个 harness，然后把它对准了一个模型。
Beren Millidge 在 2023 年的文章《作为自然语言计算机的脚手架 LLM》中给出了一个精准的类比：裸 LLM 是没有内存、没有硬盘、没有 I/O 的 CPU。上下文窗口是内存，快但有限；外部数据库是硬盘，大但慢；工具集成是设备驱动；Harness 是操作系统。我们重新发明了冯·诺依曼架构，因为这是任何计算系统的自然抽象。
三个工程层级
围绕模型有三层同心圆：
- 提示词工程 — 设计模型接收的指令
- 上下文工程 — 管理模型看到什么、什么时候看到
- Harness 工程 — 包含前两者，再加上完整的应用基础设施：工具编排、状态持久化、错误恢复、验证循环、安全执行、生命周期管理
Harness 不是提示词的包装层，而是让自主 Agent 行为成为可能的完整系统。
生产级 Harness 的 12 个组件
综合 Anthropic、OpenAI、LangChain 以及更广泛的实践者社区，一个生产级 Agent Harness 由 12 个独立组件构成：
1. 编排循环
这是 Harness 的心跳。它实现「思考-行动-观察」（TAO）循环，也叫 ReAct 循环：组装提示词 → 调用 LLM → 解析输出 → 执行工具调用 → 将结果反馈回去 → 重复直到完成。
机制上，这往往只是一个 while 循环。复杂性不在循环本身，而在循环管理的所有东西里。Anthropic 将自己的运行时描述为一个「笨循环」——所有智能都住在模型里，Harness 只负责管理轮次。
2. 工具
工具是 Agent 的手。它们以 schema 形式定义（名称、描述、参数类型），注入到 LLM 的上下文中，让模型知道有哪些可用。工具层负责注册、schema 验证、参数提取、沙盒执行、结果捕获，以及将结果格式化为 LM 可读的观察结果。
Claude Code 提供六个类别的工具：文件操作、搜索、执行、网络访问、代码智能、子 Agent 生成。OpenAI Agents SDK 支持函数工具（@function_tool）、托管工具（WebSearch、CodeInterpreter、FileSearch），以及 MCP 服务器工具。
3. 记忆
记忆在多个时间尺度上运作。短期记忆是单次会话内的对话历史；长期记忆跨会话持久化。Anthropic 使用 CLAUDE.md 项目文件和自动生成的 MEMORY.md 文件；LangGraph 使用命名空间组织的 JSON Store；OpenAI 支持由 SQLite 或 Redis 驱动的 Session。
Claude Code 实现了三层记忆架构：轻量级索引（每条约 150 字符，始终加载）、按需拉取的详细主题文件、以及只通过搜索访问的原始记录。一个关键设计原则：Agent 把自己的记忆视为「提示」，在行动前会对照实际状态进行验证。
4. 上下文管理
这是很多 Agent 悄然失败的地方。核心问题是上下文腐烂——当关键内容落在窗口中间位置时，模型性能下降超过 30%（Chroma 研究结果，得到斯坦福「迷失在中间」论文印证）。即使是百万 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 模型进行 schema 约束的响应。RetryWithErrorOutputParser 等旧方法（把原始提示、失败的补全和解析错误反馈给模型）在边缘情况下仍然可用。
7. 状态管理
LangGraph 将状态建模为流经图节点的类型字典，用 reducer 合并更新。检查点在超步边界处触发，支持中断后恢复和时间旅行调试。OpenAI 提供四种互斥策略：应用内存、SDK session、服务端 Conversations API，或轻量级 previous_response_id 链接。Claude Code 采用不同的方式：git 提交作为检查点，进度文件作为结构化草稿纸。
8. 错误处理
一个每步成功率 99% 的 10 步流程，端到端成功率仍然只有约 90.4%。错误会快速累积。
LangGraph 区分四种错误类型：
- 瞬时错误：带退避重试
- LLM 可恢复错误：将错误作为 ToolMessage 返回让模型调整
- 用户可修复错误：中断请求人工输入
- 意外错误：向上冒泡用于调试
Anthropic 在工具处理程序内捕获失败，将其作为错误结果返回以保持循环运行。Stripe 的生产 Harness 把重试次数上限设为两次。
9. 护栏与安全
OpenAI SDK 实现三个层级：输入护栏（运行在第一个 Agent 上）、输出护栏（运行在最终输出上）、工具护栏（每次工具调用都运行）。一个「断路器」机制在触发时立即停止 Agent。
Anthropic 在架构上将权限执行与模型推理分离：模型决定尝试什么，工具系统决定允许什么。Claude Code 独立门控约 40 个离散工具能力，分三个阶段：项目加载时的信任建立、每次工具调用前的权限检查、以及高风险操作的明确用户确认。
10. 验证循环
这是玩具 Demo 和生产 Agent 的分水岭。Anthropic 推荐三种方式：基于规则的反馈（测试、代码检查、类型检查器）、视觉反馈（通过 Playwright 截图用于 UI 任务）、以及 LLM 作为评判者（独立的子 Agent 评估输出）。
Claude Code 创建者 Boris Cherny 指出，给模型一种验证自身工作的方式能将质量提升 2 到 3 倍。
11. 子 Agent 编排
Claude Code 支持三种执行模型：
- Fork：父上下文的字节级复制
- Teammate：独立终端面板，通过基于文件的邮箱通信
- Worktree：每个 Agent 拥有独立的 git 工作树和隔离分支
OpenAI SDK 支持 Agent 作为工具（专家处理有界子任务）和移交（专家接管完整控制权）。LangGraph 将子 Agent 实现为嵌套状态图。
12. 生命周期管理
除了以上 11 个组件，生命周期管理贯穿 Harness 始终——从 Agent 初始化、运行态监控、到优雅终止。它决定了 Agent 何时启动、何时暂停、何时销毁，是连接所有其他组件的底层脉络。
循环实际如何运转
了解了组件，再看一个完整循环的运作方式：
- 提示词组装：Harness 构建完整输入——系统提示 + 工具 schema + 记忆文件 + 对话历史 + 当前用户消息。重要上下文被放在提示词的开头和结尾（来自「迷失在中间」的发现）。
- LLM 推理：组装好的提示词发送给模型 API，模型生成输出 token——文本、工具调用请求，或两者都有。
- 输出分类：如果模型只输出文本且没有工具调用，循环结束。如果请求了工具调用，进入执行。如果请求了移交，更新当前 Agent 并重新开始。
- 工具执行：对每个工具调用，Harness 验证参数、检查权限、在沙盒环境中执行、捕获结果。只读操作可以并发运行；写入操作串行运行。
- 结果打包：工具结果被格式化为 LLM 可读的消息。错误被捕获并作为错误结果返回，让模型可以自我纠正。
- 上下文更新：结果追加到对话历史。如果接近上下文窗口限制，Harness 触发压缩。
- 循环：返回第 1 步，重复直到终止。
终止条件是分层的：模型产生无工具调用的响应、超过最大轮次限制、token 预算耗尽、护栏断路器触发、用户中断、或返回安全拒绝。一个简单问题可能只需 1~2 轮，一个复杂的重构任务可以在多轮中串联几十次工具调用。
对于跨越多个上下文窗口的长时间运行任务，Anthropic 开发了一种两阶段「Ralph Loop」模式：初始化 Agent 负责建立环境（初始化脚本、进度文件、功能列表、初始 git 提交），然后后续每个会话中的编码 Agent 读取 git 日志和进度文件来定位自身，选择优先级最高的未完成功能，完成后提交并写入摘要。文件系统在上下文窗口之间提供连续性。
主流框架如何实现
Anthropic Claude Agent SDK 通过单一的 query() 函数暴露 Harness，创建 Agent 循环并返回流式消息的异步迭代器。运行时是一个「笨循环」，所有智能住在模型里。Claude Code 使用收集-行动-验证循环：收集上下文（搜索文件、阅读代码）→ 采取行动（编辑文件、运行命令）→ 验证结果（运行测试、检查输出），然后重复。
OpenAI Agents SDK 通过 Runner 类实现 Harness，支持异步、同步、流式三种模式。SDK 是「代码优先」的——工作流逻辑用原生 Python 表达，而非图 DSL。Codex Harness 在此基础上扩展出三层架构：Codex Core（Agent 代码 + 运行时）、App Server（双向 JSON-RPC API）、客户端界面（CLI、VS Code、网页应用）。所有界面共享同一个 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（正在演化为微软 Agent Framework）开创了对话驱动的编排方式。其三层架构（Core、AgentChat、Extensions）支持五种编排模式：顺序、并发（扇出/扇入）、群聊、移交，以及 magentic（管理 Agent 维护动态任务账本，协调各专家 Agent）。
脚手架比喻的精确含义
脚手架这个比喻不是装饰性的，它很精准。建筑脚手架是让工人能够到达他们否则无法触及位置的临时基础设施。它不负责建设，但没有它，工人上不了高层。
关键洞察在于：脚手架在建筑完工后会被拆除。随着模型改进，Harness 的复杂性应该降低。Manus 在六个月内重写了五次，每次重写都在去除复杂性——复杂的工具定义变成了通用的 shell 执行，「管理 Agent」变成了简单的结构化移交。
这指向一个协同演化原则：模型现在与特定 Harness 一起在训练循环中进行后训练。Claude Code 的模型学会了使用它被训练时配合的那个特定 Harness。改变工具实现可能因为这种紧密耦合而降低性能。
Harness 设计的「面向未来测试」是：如果随着模型能力提升，性能能够提升而不需要增加 Harness 复杂性，那么设计就是健全的。
每个 Harness 都面临的七个决策
单 Agent 还是多 Agent：Anthropic 和 OpenAI 都建议先把单 Agent 做到极致。多 Agent 系统增加开销（路由需要额外的 LLM 调用，移交时上下文会丢失）。只在工具数量超过约 10 个重叠工具、或存在明显独立的任务域时才拆分。
ReAct 还是计划-执行：ReAct 在每一步交织推理和行动（灵活但每步成本更高）。计划-执行将规划与执行分离。LLMCompiler 报告比顺序 ReAct 快 3.6 倍。
上下文窗口管理策略：五种生产方式——基于时间的清除、对话摘要、观察屏蔽、结构化笔记、子 Agent 委托。ACON 研究表明，通过优先保留推理轨迹而非原始工具输出，可以在保持 95% 以上准确率的同时减少 26%~54% 的 token 用量。
验证循环设计：计算验证（测试、代码检查器）提供确定性的基准真相。推理验证（LLM 作为评判者）能捕获语义问题但增加延迟。Martin Fowler 的 Thoughtworks 团队将其框架化为：指南（前馈，行动前引导）和传感器（反馈，行动后观察）。
权限和安全架构：宽松型（快但有风险，自动批准大多数操作）还是限制型（安全但慢，每次操作都需要批准）。选择取决于部署场景。
工具范围策略：更多工具往往意味着更差的性能。Vercel 从 v0 中删除了 80% 的工具，结果更好了。Claude Code 通过懒加载实现了 95% 的上下文减少。原则是：只暴露当前步骤所需的最小工具集。
Harness 厚度：多少逻辑住在 Harness 里，多少交给模型。Anthropic 押注于薄 Harness 和模型改进。基于图的框架押注于显式控制。Anthropic 随着新模型版本将那些能力内化，定期从 Claude Code 的 Harness 中删除规划步骤。
Harness 就是产品
使用相同模型的两个产品，仅凭 Harness 设计就可以产生截然不同的性能。TerminalBench 的证据很清楚：只改变 Harness，就能让 Agent 的排名移动 20 个以上的位次。
Harness 不是一个已解决的问题，也不是一个商品化的层。它是真正硬核的工程所在：把上下文作为稀缺资源来管理，设计在失败累积之前就能捕获失败的验证循环，构建能提供连续性而不产生幻觉的记忆系统，以及在「要构建多少脚手架」与「留多少给模型」之间做出架构决策。
这个领域正在向更薄的 Harness 方向演进，因为模型在持续改进。但 Harness 本身不会消失。即使是最强大的模型，也需要某个东西来管理它的上下文窗口、执行它的工具调用、持久化它的状态、以及验证它的工作。
下次你的 Agent 失败时，不要怪模型，看看 Harness。