引言：问题不在模型，在模型周围的一切

你搭建过一个聊天机器人，接入了 ReAct 循环，挂了几个工具，演示效果不错。然后你尝试把它做成生产级产品，问题随之而来：模型记不住三步前做了什么，工具调用静默失败，上下文窗口被垃圾填满。问题不在模型，在模型周围的一切。

LangChain 用一个案例证明了这一点：只改了包裹 LLM 的基础设施，模型权重完全没动，在 TerminalBench 2.0 上的排名从 30 名开外直接跳到第 5。另一个研究项目让 LLM 自己优化基础设施，通过率达到 76.4%，超过了人工设计的系统。这套基础设施现在有了一个正式的名字：Agent Harness。

什么是 Agent Harness

Agent Harness 是包裹 LLM 的完整软件基础设施：编排循环、工具、记忆、上下文管理、状态持久化、错误处理、安全护栏。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 是操作系统。正如 Millidge 所写：我们重新发明了冯·诺依曼架构，因为这是任何计算系统的自然抽象。

三个工程层级

围绕模型有三个同心圆层级：

提示词工程：负责设计模型接收的指令，包括 System Prompt、Few-shot 示例等。

上下文工程：管理模型看到什么、什么时候看到，包括记忆检索、上下文压缩、信息注入策略。

Harness 工程：包含前两者，再加上完整的应用基础设施：工具编排、状态持久化、错误恢复、验证循环、安全执行、生命周期管理。

Harness 不是提示词的包装层，而是让自主 agent 行为成为可能的完整系统。想深入了解 Agent 的整体架构，可参考 AI Agent 与多智能体 专题。

生产级 Harness 的 12 个组件

综合 Anthropic、OpenAI、LangChain 和更广泛的实践者社区，一个生产级 agent harness 有 12 个独立组件。

1. 编排循环

这是心跳所在。它实现思考-行动-观察（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 的窗口，随着上下文增长，指令遵循能力也会退化。生产级策略包括：

压缩：在接近上限时对对话历史进行摘要（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 约束的响应。

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. 可观测性与治理

可观测性确保每次模型调用、工具调用、检索、报错、重试、token 成本、延迟都能被追踪。治理则定义 agent 的权限：能不能发邮件、改代码、调 API、读私有数据？谁来审批？谁来审计？这两层是生产 agent 不可或缺的组成部分。更多关于工作流编排的内容可参考 Workflow 与自动化。

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

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

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

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

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

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

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

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

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

终止条件是分层的：模型产生无工具调用的响应、超过最大轮次限制、token 预算耗尽、护栏断路器触发、用户中断、或返回安全拒绝。一个简单问题可能只需 1 到 2 轮，一个复杂的重构任务可以在多轮中串联几十次工具调用。

从 Harness 到 State-Aware Runtime

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

状态管理的关键挑战

状态转移：Agent 的每一步执行都应建模为可验证的状态转移。系统必须知道当前状态是什么，哪些动作只是候选，哪些动作已经提交，哪些状态可以回滚。

长上下文 ≠ 长期状态管理：简单粗暴地将几万字的历史对话塞给模型，非但不能获得稳定的记忆，反而会引发灾难：早期严格的设定可能被中间的闲聊覆盖；临时的推测可能被模型当作真理固化；摘要压缩过程可能悄悄篡改了任务的初衷。

错误状态被提交：如果模型生成了一个危险的 API 调用，只要被外部 Validator 拦截了，系统依然安全。但如果这个调用已经切实改变了外部数据库或游戏世界的状态，错误就已经从语言幻觉变成了外部状态污染的物理影响。

评估方式的转变

传统评测大模型（如 MMLU）只看最终答案。但评估 Agent 时这种思路完全失效。Agent 的失败是在过程中发酵的，具有极强的级联传播特性。因此需要 Trace-Native Evaluation（轨迹原生评估）：记录模型输出、工具调用、工具返回、环境状态变化、上下文快照、错误、重试、恢复动作、token 使用、延迟和成本。然后再判断三件事：结果是否正确，路径是否合理，评估器本身是否可信。

本体驱动：让约束来自业务结构

传统的 Harness 方案能让 Agent“更稳定”，但稳定的边界是工程边界——规则是人写的，约束是配置出来的，合规是靠 Prompt 维持的。一旦业务复杂度超过工程维护能力，约束就开始失效。本体（Ontology）驱动的方案实现的是另一件事：让约束直接来自业务结构本身。

本体如何改变三个技术支柱

架构约束：业务规则不再以自然语言形式存在于 Prompt 里，而是被显式建模为可查询、可校验的结构。工具也不是在 Agent 层临时定义的，而是由本体层统一管理——Agent 能用什么、如何触发、执行流程是什么，都由结构说了算。

上下文工程：Agent 启动前，认知引擎从本体中抽取与当前任务相关的语义子图，将最相关的上下文动态注入推理语境，而不是把所有信息一股脑塞进去。一致性保障：业务知识由统一的语义网络管理，过期信息、冲突内容可被系统性处理。

反馈闭环：不依赖主观评估，而是基于结构进行客观校验。企业中大量的判断本质上是可以被规则化的——是否超出额度、是否满足前置条件、是否符合流程逻辑。这些判断不需要“理解”，可以直接验证。

代码作为 Agent Harness：Code as Agent Harness

来自 UIUC、Meta 和斯坦福的综述《Code as Agent Harness》提出了一个不同的视角：当 Agent 被放进长期任务环境里，真正把推理、行动、反馈、验证和协作串起来的操作对象是代码。这里的代码不只是模型最终生成的一段程序，而是 Agent 在 harness 中不断生成、运行、修改、保存和共享的一系列代码化中间物：Plan.md、测试脚本、shell 命令、patch、执行日志、workflow、技能库、仿真器、验证器，甚至共享仓库状态。

代码有自然语言不具备的三个属性：可执行、可检查、有状态。可执行意味着模型的意图可以变成真实操作；可检查意味着执行过程会产生客观反馈；有状态意味着任务进度可以被持久保存。因此，代码是 harness 中最稳定、最可操作的状态载体。

从 Framework 到 Platform

如果只看工具生态，Agent 正在从 framework 走向 platform。Framework 解决的是局部抽象：agent、tool、memory、loop。Platform 要解决的是完整生产系统：durable workspace、managed sandbox、identity、billing、observability、evaluation、governance、human handoff。早期大家拼的是谁能最快搭一个 Agent loop，现在拼的是谁能让这个 loop 长期可靠运行。关于模型部署的更多实践可参考 模型部署与推理优化。

结语

大模型会继续疯狂变强，上下文窗口会被彻底打爆，具身智能和多模态 API 将如潮水般涌来。但当潮水褪去，真正的工业级瓶颈绝不仅是模型够不够聪明。决定胜负的标尺将变为：系统能否在极度混乱的外部环境中长期维持内部状态？能否依靠机制截杀错误操作的提交？能否留下可解释的审计轨迹，并在雪崩发生后优雅地回滚恢复？模型负责无限生成可能性，Harness 负责提供物理的约束环境，而 State-Aware Runtime 负责维护状态的一致性、审计过程的忠实、阻止灾难的提交。Agent 竞逐的下半场，谁能率先把这些高能力但不稳定的模型，安全地装配进一套可审计、可恢复的状态机系统中，谁才能拥有下一代智能操作系统的真正的护城河。

FAQ

Agent Harness 和传统的 Prompt Engineering 有什么区别？ Prompt Engineering 只关注如何设计输入文本以引导模型输出，而 Agent Harness 是完整的执行基础设施，包括工具调用、状态管理、错误处理、安全护栏等。Harness Engineering 包含 Prompt Engineering 和 Context Engineering，是让 Agent 在真实世界中可靠运行的系统工程。

Harness 和 Scaffold 这两个概念有何不同？ Scaffold（脚手架）是围绕模型的行为定义层，包括系统提示词、工具描述、输出格式等，是模型能看到的信息。Harness 是执行层，驱动模型运行循环、处理工具调用、管理状态。简单判断：脚手架是信息（模型能看到），Harness 是逻辑（模型看不到但驱动它运行）。

生产级 Harness 中最容易被忽视的组件是什么？ 错误处理和可观测性。一个每步成功率 99% 的 10 步流程，端到端成功率只有约 90.4%，错误会快速累积。没有完善的错误分类和重试策略，以及完整的执行轨迹追踪，Agent 在长任务中几乎必然失败，且难以定位原因。