引言：为什么模型越强，Agent 越容易翻车？

2024-2025 年，AI Agent 成为企业落地的核心形态。智能体能够自主规划、调用工具、连续执行多步任务，在演示中表现亮眼。然而，一旦进入真实业务场景，问题便集中爆发：模型记不住三步前的决策、工具调用静默失败、上下文窗口被冗余信息填满、推理逻辑偏离业务规则。

根本原因不在模型本身，而在于模型周围缺乏一套稳定的运行时结构。LangChain 曾用一个典型案例证明：仅改变包裹 LLM 的基础设施，模型权重完全不动，在 TerminalBench 2.0 上的排名就从 30 名开外直接跃升至第 5。另一个研究项目让 LLM 自己优化基础设施，通过率达到 76.4%，超过了人工设计的系统。

这套基础设施如今有了正式的名字——Agent Harness。

什么是 Agent Harness？

Agent Harness 是包裹大语言模型的完整软件基础设施，包含编排循环、工具、记忆、上下文管理、状态持久化、错误处理、安全护栏等组件。Anthropic 在 Claude Code 文档中直接写明：SDK 就是“驱动 Claude Code 的 agent harness”。OpenAI 的 Codex 团队也采用同样的框架，将“agent”和“harness”视为等价概念，专指让 LLM 变得有用的非模型基础设施。

LangChain 的 Vivek Trivedy 给出了一个清晰的定义：如果你不是模型本身，你就是 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 验证、参数提取、沙盒执行、结果捕获，以及将结果格式化成 LLM 可读的观察结果。

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 的窗口，随着上下文增长，指令遵循能力也会退化。

生产级策略包括：

压缩：在接近上限时对对话历史进行摘要，保留架构决策和未解决的 bug，丢弃冗余的工具输出。

观察屏蔽：隐藏旧的工具输出，但保留工具调用可见。

即时检索：维护轻量级标识符，动态加载数据，而不是加载完整文件。

子 agent 委托：每个子 agent 进行大范围探索，但只返回 1000 到 2000 token 的压缩摘要。

5. 提示词构建

这一步组装模型在每一步实际看到的内容，是分层的：系统提示、工具定义、记忆文件、对话历史、当前用户消息。OpenAI 的 Codex 使用严格的优先级栈：服务器控制的系统消息（最高优先级）、工具定义、开发者指令、用户指令（级联的 AGENTS.md 文件，32 KiB 上限），然后是对话历史。

6. 输出解析

现代 Harness 依赖原生工具调用，模型返回结构化的 tool_calls 对象，而不是需要解析的自由文本。Harness 检查：有工具调用吗？执行并循环。没有工具调用？那就是最终答案。对于结构化输出，OpenAI 和 LangChain 都支持通过 Pydantic 模型进行 schema 约束的响应。

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. 可观测性与轨迹记录

生产级 Harness 必须记录完整的执行轨迹，包括每一步的输入、输出、工具调用、状态变更。这些轨迹不仅用于调试和审计，还可作为后续优化的数据源。小米的 HarnessX 系统将轨迹存入共享缓冲区，同时驱动框架演进和模型微调。

循环实际如何运转：逐步演练

了解了组件，再来看一个完整循环的运作方式。

第 1 步（提示词组装）：Harness 构建完整输入：系统提示 + 工具 schema + 记忆文件 + 对话历史 + 当前用户消息。重要上下文被放在提示词的开头和结尾（来自“迷失在中间”的发现）。

第 2 步（LLM 推断）：组装好的提示词发送给模型 API，模型生成输出 token：文本、工具调用请求，或两者都有。

第 3 步（输出分类）：如果模型只输出文本且没有工具调用，循环结束。如果请求了工具调用，进入执行。如果请求了移交，更新当前 agent 并重新开始。

第 4 步（工具执行）：对每个工具调用，Harness 验证参数、检查权限、在沙盒环境中执行、捕获结果。只读操作可以并发运行；写入操作串行运行。

第 5 步（结果打包）：工具结果被格式化为 LLM 可读的消息。错误被捕获并作为错误结果返回，让模型可以自我纠正。

第 6 步（上下文更新）：结果追加到对话历史。如果接近上下文窗口限制，Harness 触发压缩。

第 7 步（循环）：返回第 1 步，重复直到终止。

终止条件是分层的：模型产生无工具调用的响应、超过最大轮次限制、token 预算耗尽、护栏断路器触发、用户中断、或返回安全拒绝。

前沿实践：可学习控制器与自适应演进

HarnessBridge：可学习的双向控制器

传统 Harness 依赖人工规则，在长时序任务中面临两大痛点：交互轨迹冗余信息过多，Token 开销大、关键状态被掩盖；智能体频繁输出无效、重复动作，浪费交互步数。UCLA 团队提出的 HarnessBridge 将传统静态框架改造为端到端可学习双向控制器。

HarnessBridge 由两大核心模块组成：

观测投影：对原始交互轨迹做筛选、压缩，提炼出对决策有用的精简状态。它新增活跃状态索引，前置展示未解决错误、待完成目标、已确认事实等核心信息，并对每一轮历史单元执行保留、压缩、丢弃三类决策。

动作投影：校验模型输出的待执行动作，拦截低效、无效操作，并给出基于历史轨迹的改进建议。

实验基于 SWE-bench 和 Terminal-Bench 两大代码类基准测试，采用统一指令微调训练轻量化模型。结果显示，HarnessBridge 在开源及多款商用大模型上均表现优异，任务成功率持平或超越传统框架，Token 用量与交互轮次大幅下降。例如在 Terminal-Bench 2.0 上，Token 最高降低 77.5%，成功率提升 11.2 个百分点。

HarnessX：可组合、自适应、可演进的框架工厂

小米团队提出的 HarnessX 将框架本身视为可优化的对象，包含三大核心能力：

可组合架构：将 Harness 抽象为标准化处理器与八大生命周期钩子，划分九大优化维度，依托类型约束实现组件自由插拔与安全复用。

AEGIS 自适应演进引擎：把框架演进映射为符号空间强化学习，通过解析、规划、演化、评判四阶段流水线，针对性解决奖励欺骗、灾难性遗忘、探索不足三大问题，并采用变体隔离策略适配异构任务场景。

框架-模型协同进化：搭建共享轨迹缓冲区，结合跨框架 GRPO 算法同步优化框架与模型。

实验在 GAIA、ALFWorld 等五大主流智能体基准上开展，结果显示 HarnessX 平均带来 14.5% 的性能提升，最高达 44.0%，且模型基线越弱收益越显著。

Harness-1：状态外部化认知卸载

针对搜索智能体需同时学习语义决策与状态管理的缺陷，Harness-1 提出状态外部化架构：将文档台账、证据记录等繁琐状态维护工作交由专用工具承担，大模型仅专注搜索、策展、验证等语义决策。工具搭建分层工作内存，集成候选池、证据图、验证记录等模块，并配备自动播种、文本压缩去重、文档重要性分级等优化机制。

在网页、金融、专利、多跳问答等 8 项检索基准中，Harness-1 平均策划召回率达 0.730，领先主流开源模型 11.4 个百分点，跨域泛化能力极强。

本体驱动：从技术可控到业务可控

传统 Harness 方案能让 agent“更稳定”，但稳定的边界是工程边界——规则是人写的，约束是配置出来的，合规是靠 Prompt 维持的。这套体系的天花板很清晰：一旦业务复杂度超过工程维护能力，约束就开始失效。

本体驱动的方案实现的是另一件事：让约束直接来自业务结构本身。企业的对象、关系、规则被统一建模为本体，Agent 在执行任务时不是拿到上下文就开始生成，而是必须先进入这层语义结构，在既定的业务关系中完成推理和决策。

本体驱动的 Harness 带来三个实质性的转变：

Agent 不再只是执行工具，而是具备业务语义的参与者；

系统不需要为每个场景重新构建约束，可以在统一语义底座上复用；

在模型持续迭代的过程中，业务规则层保持稳定，不随模型版本漂移。

悦点科技的 Knora 平台将本体驱动方案落地为分层协作的系统架构，本体层以标签属性图存储本体模型 Schema，定义了实体、关系、事件、Action、Logic 五个核心概念。认知引擎层在本体和 Agent 之间做桥接，Agent 执行层是纯粹的执行者，工具从哪来、怎么用、边界在哪，全部由本体层定义。

从 Harness 到 State-Aware Runtime

Harness 解决的是静态问题：“Agent 的外围系统由哪些组件构成？”而更深层的动态问题是：“这些组件，如何共同维护一个长期稳定、可审计、可回滚、可恢复的运行状态？”这个方向被称为 State-Aware Runtime（状态感知运行时）。

State-Aware Runtime 不是单纯给 Agent 加一个 memory，也不是把历史对话塞进长上下文，而是把 Agent 的每一步执行都建模为可验证的状态转移。系统必须知道当前状态是什么，哪些动作只是候选，哪些动作已经提交，哪些状态可以回滚，哪些失败需要隔离或交给人类处理。

核心设计原则包括：

严格区分候选输出与已提交状态：模型生成的意图在提交执行前必须经过校验，错误状态不能被写入长期记忆或外部系统。

轨迹原生评估：不要只问最后做成了没有，必须要问这个结果是如何一步步生成的，中间状态有无被污染，系统能否精准定位错误并执行恢复。

确定性门禁：任何导致历史任务退化的修改不得上线，高风险修改支持人工审批。

FAQ

Agent Harness 与 LangChain、OpenAI SDK 是什么关系？ LangChain、OpenAI SDK 是 Harness 的具体实现框架。它们提供了编排循环、工具调用、记忆管理等基础设施，开发者可以基于这些框架构建自己的 Harness。但 Harness 是一个更广泛的概念，任何包裹 LLM 并使其具备自主行为能力的软件系统都可以称为 Harness。

Harness 工程与提示词工程的根本区别是什么？ 提示词工程关注如何设计模型接收的指令文本；Harness 工程则关注完整的应用基础设施，包括工具编排、状态持久化、错误恢复、验证循环、安全执行、生命周期管理等。提示词工程是 Harness 工程的一个子集，Harness 工程是让自主 agent 行为成为可能的完整系统。

可学习控制器（如 HarnessBridge）相比传统规则式 Harness 有哪些优势？ 可学习控制器通过观测投影和动作投影两个模块，动态优化上下文压缩和动作校验，能够根据历史轨迹自适应调整策略。相比传统规则式 Harness，它大幅降低 Token 消耗和交互轮次，同时保持或提升任务成功率。基于轻量化模型训练，泛化性强，可无缝迁移到不同的大模型上。