AReAct循环、几个工具以及一段写得很好的系统提示词，就能在演示中取得令人惊喜的成果。
但一旦任务需要10步以上，情况就会急转直下：模型仿佛忘了三步之前做了什么，工具调用悄然失败，上下文窗口也很快被垃圾信息填满。
问题不在于模型，而在于模型周围的一切。
LangChain 证明了这一点：他们仅对封装其大语言模型的基础设施进行了调整（使用相同的模型、相同的权重），便从排名前30名之外跃升至TerminalBench 2.0的第5名。
一项独立研究项目通过让LLM优化基础设施本身，实现了76.4%的通过率，超过了人工设计的系统。
该基础设施如今有了一个名字：代理 Harness。
什么是代理 Harness？
这一术语于2026年初正式确定，但这一概念早在很久以前就已存在。
该框架是封装大型语言模型的完整软件基础设施，包括编排循环、工具、内存、上下文管理、状态持久化、错误处理以及安全防护措施。
Anthropic的Claude Code文档简洁地指出：SDK是"驱动Claude Code的代理工具包。"
我们非常喜欢LangChain的Vivek Trivedy提出的经典公式："如果你不是模型，那你就是工具包。"
换句话说，"智能体"是一种涌现出来的行为：一种具有目标导向、会使用工具并能自我修正的实体，用户正是与这种实体进行交互。而"框架"则是产生这种行为的机制。当有人声称"我构建了一个智能体"时，他们实际上是指自己构建了一个框架，并将其指向某个模型。
贝伦·米利奇在2023年的论文中精确地提出了这一类比：
- 一个未经训练的大型语言模型就像一台没有内存、没有硬盘、也没有输入输出设备的CPU。
- 上下文窗口充当RAM（快速但有限）--SKILL是辅助写提示词，而提示词也是上下文不可分割的一部分。
- 外部数据库充当磁盘存储（容量大但速度慢）--知识库、数据库、素材库都是。
- 工具集成充当设备驱动程序。
线束是操作系统。
三个工程层次
三个同心的工程层次环绕着该模型：
- 提示工程塑造了模型接收到的指令。
- 上下文工程管理着模型何时以及看到什么内容。
- Harness工程涵盖这两方面，以及整个应用基础设施：工具编排、状态持久化、错误恢复、验证循环、安全实施和生命周期管理。
该框架并非对提示的简单封装，而是一个完整的系统，使自主智能体的行为成为可能。
生产级工具箱的11个组件
综合Anthropic、OpenAI、LangChain以及更广泛的从业者社区的经验，一个生产级代理工具箱包含十一个独特的组件。让我们逐一了解一下。
1. 编排循环
这就是心跳机制。它实现了"思考---行动---观察"（TAO）循环，也称为ReAct循环。该循环的运行流程如下：组装提示、调用大语言模型、解析输出、执行任何工具调用、将结果反馈回系统，如此反复，直至完成。
从机械角度来看，这通常只是一个while循环。复杂性存在于循环所处理的方方面面，而非循环本身。Anthropic将他们的运行时描述为"一个愚蠢的循环"，其中所有智能都存在于模型中，而控制装置仅负责管理轮次。
2.插件/工具
工具是代理的双手。它们被定义为模式（名称、描述、参数类型），注入到大语言模型的上下文中，以便模型了解可用的内容。工具层负责注册、模式验证、参数提取、沙箱执行、结果捕获，以及将结果格式化为大语言模型可读的观测数据。
Claude Code 提供了六大类工具：文件操作、搜索、执行、网页访问、代码智能以及子代理启动。OpenAI 的 Agents SDK 支持函数工具（通过function_tool）、托管工具（WebSearch、CodeInterpreter、FileSearch）以及 MCP 服务器工具。
3. 内存
记忆以多种时间尺度运行。短期记忆是指单次会话内的对话历史。长期记忆则贯穿多个会话：Anthropic 使用项目文件和自动生成的文件；LangGraph 则使用按命名空间组织的 JSON 存储；OpenAI 支持由 SQLite 或 Redis 提供支持的会话。
Claude Code 采用三层架构：轻量级索引（每条记录约150个字符，始终加载）、按需调取的详细主题文件，以及仅可通过搜索访问的原始文本记录。
4. 上下文管理
许多代理正是在这里悄然失败。核心问题在于上下文衰减：当关键内容位于窗口中间位置时，模型性能会下降30%以上。
即使在百万标记的窗口中，随着上下文增大，指令遵循能力也会出现下降。
生产策略包括：
- 压缩：在接近限制时汇总对话历史（Claude Code 保留架构决策和未解决的错误，同时丢弃冗余的工具输出）
- 观察掩码：JetBrains 的 Junie 隐藏旧工具输出，同时保留工具调用可见
- 即时检索：保持轻量级标识符并动态加载数据（Claude Code 使用 grep、glob、head、tail，而非加载完整文件）
- 子代理委托：每个子代理广泛探索，但仅返回1,000至2,000个标记的精简摘要
Anthropic 的上下文工程指南指出，其目标是：找到一组尽可能小的高信号标记，以最大化实现预期结果的可能性。
5. 提示词
这汇总了模型在每一步实际看到的内容。它采用层次结构，包括系统提示、工具定义、记忆文件、对话历史以及当前用户消息。
OpenAI 的 Codex 使用严格的优先级堆栈：服务器控制的系统消息（即系统提示词、用户提示词，优先级最高）、工具定义、开发者说明、用户说明（分层文件，32 KiB 限制），然后是对话历史。
6. 输出解析
现代约束依赖于原生工具调用，其中模型返回结构化tool_calls对象，而非必须进行解析的自由文本。
该工具箱会检查是否存在任何工具调用？如果存在，它将执行这些调用并进入循环；如果不存在，则给出最终答案。
对于结构化输出，OpenAI 和 LangChain 均支持通过 Pydantic 模型实现模式约束的响应。
像RetryWithErrorOutputParser这样的传统方法（会将原始提示、失败的完成内容和解析错误重新输入模型）仍适用于边缘情况。
7. 状态管理
LangGraph 模型将状态表示为在图节点间流动的类型化字典，由归约器合并更新。
检查点记录发生在超级步骤边界，支持中断后恢复及时间旅行调试。
OpenAI 提供四种互斥策略：应用内存、SDK 会话、服务器端对话 API，或轻量级的 previous_response_id 链接。Claude Code 则采取了不同的方法：以 Git 提交作为检查点，以进度文件作为结构化暂存区。
8. 错误处理
原因如下：即使每一步的成功率高达99%，经过10步的累积，最终端到端的成功率也仅约为90.4%。
LangGraph 区分了四种错误类型：暂时性错误（带退避重试）、大模型可恢复错误（以 ToolMessage 形式返回错误，以便模型进行调整）、用户可修复错误（中断以等待人工输入）和意外错误（上抛以用于调试）。Anthropic 会捕获工具处理程序中的失败，并将其作为错误结果返回，以保持循环持续运行。Stripe的生产环境限制重试次数为两次。
9. 防护措施与安全
OpenAI的SDK实施了三个级别：输入防护措施（在首个代理上运行）、输出防护措施（在最终输出上运行）和工具防护措施（在每次工具调用上运行）。
"绊线"机制在触发时会立即停止代理。
Anthropic 在架构上将权限执行与模型推理分离。模型决定尝试做什么；工具系统决定允许什么。Claude Code 独立管理约 40 种不同的工具功能，分为三个阶段：项目加载时建立信任、每次调用工具前进行权限检查，以及对高风险操作进行明确的用户确认。
10. 验证循环
这正是玩具演示与生产级代理之间的区别所在。Anthropic 推荐三种方法：基于规则的反馈（测试、linter、类型检查器）、视觉反馈（通过 Playwright 截图以执行 UI 任务），以及以大语言模型为裁判（由一个独立的子代理对输出进行评估）。
克劳德代码的创造者鲍里斯·切尔尼指出，为模型提供一种验证其工作成果的方法，可将质量提升2到3倍。
11. 子代理编排
Claude Code 支持三种执行模式：Fork（父上下文的字节级完全副本）、Teammate（独立终端窗格，采用基于文件的邮箱通信）和 Worktree（独立的 Git 工作树，每个代理拥有隔离的分支）。
OpenAI的SDK支持代理作为工具（专家处理有限子任务）和交接（专家完全接管控制）。LangGraph将子代理实现为嵌套状态图。
分步操作指南
现在你已经了解了各个组件，让我们来追踪它们如何在单个周期中协同工作。
- 步骤1（提示组装）：线束构建完整输入：系统提示 + 工具模式 + 内存文件 + 对话历史 + 当前用户消息。重要上下文位于提示的开头和结尾（即"迷失于中间"现象）。
- 步骤2（大语言模型推理）：组装好的提示将发送至模型API。模型会生成输出标记：文本、工具调用请求，或两者兼有。
- 步骤3（输出分类）：如果模型生成的文本中没有工具调用，则循环结束。如果模型请求了工具调用，则进入执行阶段。如果请求了交接，则更新当前代理并重新启动。
- 步骤4（工具执行）：对于每次工具调用，该框架会验证参数、检查权限，在沙箱环境中执行，并捕获结果。只读操作可并发运行；修改性操作则按顺序执行。
- 步骤5（结果封装）：工具结果被格式化为大语言模型可读的消息。错误会被捕获并作为错误结果返回，以便模型能够自我纠正。
- 第6步（上下文更新）：将结果追加到对话历史中。如果接近上下文窗口限制，框架会触发压缩。
- 第7步（循环）：返回第1步。重复直至终止。
终止条件分层设置：模型生成无工具调用的回复、达到最大轮次限制、令牌预算耗尽、触发防护机制、用户中断，或返回安全拒绝。一个简单的问题可能需要1到2轮次才能完成。一项复杂的重构任务可能在多个回合中串联数十次工具调用。
对于跨越多个上下文窗口的长时间任务，Anthropic 开发了一种两阶段的"Ralph Loop"模式。
它使用一个初始化代理来搭建环境（初始化脚本、进度文件、功能列表、首次 Git 提交），随后在每一轮会话中，一个编码代理会读取 Git 日志和进度文件以确定自身位置，挑选优先级最高的未完成功能，对其进行开发、提交，并撰写摘要。
文件系统在上下文窗口之间提供连续性。
框架如何实现该模式
Anthropic 的 Claude Agent SDK 通过一个single query()函数公开了该工具包，该函数会创建智能体循环并返回一个流式传输消息的异步迭代器。
运行时是一个"哑循环"。所有智能都存在于模型中。Claude Code 采用一种收集-行动-验证的循环：收集上下文（搜索文件、读取代码），采取行动（编辑文件、运行命令），验证结果（运行测试、检查输出），然后重复。
OpenAI 的代理 SDK 通过 Runner 类实现 Harness，提供三种模式：异步、同步和流式。
该SDK采用"代码优先"模式：工作流逻辑以原生Python语言而非图式DSL来表达。Codex工具包在此基础上扩展为三层架构：Codex Core（代理代码 + 运行时）、应用服务器（双向JSON-RPC API）以及客户端界面（CLI、VS Code、Web应用）。 所有界面都共享同一套控制台，这就是为什么"Codex 模型在 Codex 界面上使用起来比普通聊天窗口更顺手。"
LangGraph 将 Harness 建模为一个显式状态图。两个节点（llm_call和tool_node) 由一条条件边连接：如果存在工具调用，则路由至 tool_node；如果不存在，则路由至 END。
LangGraph源自LangChain的AgentExecutor，该组件在v0.2版本中已被弃用，原因是其难以扩展且缺乏多智能体支持。LangChain的深度智能体明确使用了"智能体 Harness"这一术语：内置工具、规划功能（write_todos工具）、用于上下文管理的文件系统、子智能体的启动以及持久化存储。
CrewAI采用基于角色的多智能体架构：智能体（围绕大语言模型构建，由角色、目标、背景故事和工具定义）、任务（工作单元）以及团队（智能体的集合）。CrewAI的流程层提供了一种"在关键环节注入确定性与智能的骨干架构"，负责管理路由与验证，同时由团队实现自主协作。
智能体开发平台--脚手架
建筑脚手架是一种临时性基础设施，它使工人能够建造原本无法触及的结构。它本身并不参与施工，但没有它，工人就无法到达高层楼层。
关键洞察在于，当建筑完工后，脚手架便会被拆除。随着模型的不断改进，复杂性应随之降低。Manus在六个月内经历了五次重构，每次重写都消除了部分复杂性。复杂的工具定义逐渐演变为通用的外壳执行。 "管理代理"变成了简单的结构化交接。
这表明了一种协同进化原则：如今，模型在训练完成后会结合特定的工具链进行微调。Claude Code 的模型学会了使用它所接受训练时所用的特定工具链。因此，更换工具实现可能会因这种紧密耦合而降低性能。
针对线束设计的未来适应性测试表明：如果性能能够随着更强大型号的升级而提升，且无需增加线束复杂度，则该设计是合理的。
Harness 定义的七个决策
每位 Harness 架构师都面临七个选择：
- 单智能体与多智能体。Anthropic和OpenAI均要求优先最大化单智能体的效能。多智能体系统会增加额外开销（用于路由的额外大语言模型调用，以及交接过程中可能造成上下文丢失）。仅当工具数量超过约10个重叠工具，或任务领域明显存在差异时，才考虑拆分。
- ReAct与计划并执行。ReAct在每一步中交替进行推理与行动（灵活但每步成本较高）。计划并执行则将规划与执行分开。LLMCompiler相较于顺序ReAct，速度提升了3.6倍。
- 上下文窗口管理策略。五种生产方法包括基于时间的清除、对话摘要、观察屏蔽、结构化笔记记录以及子代理委派。ACON研究表明，通过优先处理推理轨迹而非原始工具输出，可在保持95%以上准确率的同时，实现26%至54%的标记数量减少。
- 验证循环设计。计算验证（测试、静态分析工具）提供确定性的基准真相。推理验证（以大语言模型充当裁判）能够捕捉语义问题，但会增加延迟。Martin Fowler 所在的 Thoughtworks 团队将此框架化为指南（前馈，行动前引导）与传感器（反馈，行动后观察）之分。
- 权限与安全架构：宽松型（速度快但风险高，大多数操作自动批准）与严格型（安全但速度慢，每项操作均需审批）。具体选择取决于部署环境。
- 工具范围策略。工具越多，性能往往越差。Vercel 在 v0 版本中移除了 80% 的工具，从而获得了更好的效果。Claude Code 通过惰性加载实现了 95% 的上下文缩减。其原则是：仅暴露当前步骤所需的最少工具集。
- 线束厚度。线束中蕴含的逻辑量与模型相比如何。Anthropic押注于薄线束和模型改进。基于图的框架则侧重于显式控制。Anthropic会定期从Claude Code的线束中删除规划步骤，因为新版本的模型已内化了这一能力。
Harness就是该产品
仅凭线束设计的不同，两款采用相同型号的产品性能可能大相径庭。TerminalBench的证据表明，仅更换线束就能使排名提升20多位。
该框架并非一个已解决的问题或通用的底层模块。它承载着诸多高难度的工程技术挑战，例如将上下文管理视为一种稀缺资源、设计能够及早发现并阻止故障恶化的验证闭环、构建既能保持连续性又不会产生幻觉的内存系统，以及在架构层面权衡究竟应多建一些支撑结构，还是更多地交由模型自行处理。
随着模型性能的提升，该领域正朝着更纤薄的线束方向发展。但线束本身并不会消失。即使是最强大的模型，也依然需要某种东西来管理其上下文窗口、执行工具调用、持久化状态并验证其工作成果。
下次你的代理失败时，别怪模型，而应看看那副 Harness。