从“玩具Demo”到“生产级Agent”的鸿沟

你搭建过一个聊天机器人，接入了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所写：我们重新发明了冯·诺依曼架构，因为这是任何计算系统的自然抽象。

三个工程层级

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

提示词工程：负责设计模型接收的指令。

上下文工程：管理模型看到什么、什么时候看到。

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

Harness不是提示词的包装层，而是让自主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. 可观测性

生产级Harness需要全面的日志、追踪和监控。包括：每次LLM调用的输入输出日志、工具执行耗时与结果、状态变更记录、错误与重试历史。OpenTelemetry是推荐的标准，LangSmith、Weights & Biases等平台提供专门的Agent追踪能力。

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

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

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

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

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

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

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

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

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

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

开源项目实践：Workspace-first 路由策略

Zleap-Agent是一个专为本地小模型设计的Agent Harness，其核心设计理念是Workspace-first：不要先问Agent能接多少工具，而是先问当前任务应该发生在哪个工作区。

具体做法是把Agent的运行环境切成不同工作区：

Main Workspace：负责理解用户目标和任务调度；

Web Search Workspace：负责搜索、网页阅读、引用整理；

CLI Workspace：负责文件读取、编辑、命令执行和测试；

业务Workspace：负责销售、财务、运营、研究等具体场景。

每个Workspace都有自己的prompt、tools、memory、history、model和permission。Agent进入哪个Workspace，就只加载当前工作区需要的内容。

这种设计的核心价值在于：不让Agent每一步都加载全部工具、记忆和历史，而是让它在当前任务所需的信息范围内工作。对于本地小模型，长上下文定位能力有限，Workspace-first能显著降低上下文负担。

可学习双向控制器：HarnessBridge

UCLA团队提出的HarnessBridge将传统人工设计的Harness改造为端到端可学习的双向控制器，包含两个核心模块：

观测投影（Observation Projection）：对原始交互轨迹做筛选、压缩，提炼出对决策有用的精简状态。对每一轮历史单元执行三类决策：保留（PASS）关键信息、压缩（COMPRESS）冗长但有用的内容、丢弃（DROP）冗余过时的内容。

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

实验结果显示，基于0.8B轻量化模型的HarnessBridge，在Terminal-Bench 2.0上Token最高降低77.5%，成功率提升11.2个百分点；在SWE-bench Verified上Token降低23.1%，成功率持平顶尖基线。更重要的是，训练一次就能泛化到GPT、Claude等商用大模型。

多智能体协作下的Harness设计

当从单智能体扩展到多智能体协作时，Harness需要额外处理：

智能体间通信：Claude Code使用基于文件的邮箱通信（Teammate模式），OpenAI支持agent作为工具和移交（handoff）。

共享状态与隔离：LangGraph将子agent实现为嵌套状态图，Claude Code的Worktree模式为每个agent提供独立的git工作树。

全局编排与调度：需要一个协调者（Orchestrator）负责分解任务、分配子任务、合并结果。

想深入了解多智能体协作，可参考 AI Agent 与多智能体。

可观测性设计

生产级Harness的可观测性覆盖三个维度：

维度指标工具示例

日志每次LLM调用、工具执行、状态变更LangSmith、自定义日志 追踪完整调用链、耗时分布OpenTelemetry、Arize 监控成功率、延迟、Token消耗、错误率Prometheus + Grafana

关键设计原则：可观测性数据本身不应成为性能瓶颈。建议异步日志、采样上报、按需保留。

总结

Agent Harness是AI Agent从玩具走向生产的必经之路。它不仅仅是提示词的包装，而是涵盖编排、工具、记忆、上下文、状态、错误、安全、验证、子agent、可观测性的完整系统。

未来，随着模型能力越来越强，Harness不会消失，而是会从“人工规则”走向“可学习、可自适应”。HarnessBridge和Workspace-first等实践已经指明了方向。

如果你想进一步探索，推荐阅读 LangChain 实战 和 AI Agent 工作流设计。

FAQ

Agent和Harness有什么区别？ Agent是涌现出来的行为，是用户交互的那个有目标、会用工具、能自我纠正的实体。Harness是产生这种行为的机器。当有人说“我做了一个agent”，他们其实是做了一个harness，然后把它对准了一个模型。

为什么需要上下文管理？即使模型有百万token窗口？ 因为上下文腐烂问题：关键内容落在窗口中间位置时，模型性能下降超过30%。即使是百万token的窗口，随着上下文增长，指令遵循能力也会退化。上下文管理的目标是用最小的token集合最大化期望结果概率。

HarnessBridge的可学习方案是否适用于所有场景？ 目前仅在代码类任务（SWE-bench、Terminal-Bench）上验证，尚未拓展至网页导航、多轮调研等场景。但其设计思路——将Harness改造为端到端可学习的双向控制器——具有通用性，未来可扩展到更多工具调用场景。