Agent Harness：让AI从聊天机器人变成真正的智能体
摘要
Harness 是包裹 LLM 的完整软件基础设施，让 AI 从聊天机器人变成真正的智能体。
核心公式："如果你不是模型，你就是 harness"
三大工程层：提示词工程、上下文工程、Harness 工程
12个生产级组件：编排循环、工具、记忆、上下文管理、输出解析、状态管理、错误处理、防护栏、验证循环、子智能体编排
关键发现：只改 harness 不改模型，TerminalBench 排名提升了 20+ 位
核心概念
Agent Harness 是包裹 LLM 的完整软件基础设施，包括：编排循环、工具、记忆、上下文管理、状态持久化、错误处理和安全防护。
类比：原始 LLM 如同没有内存、没有硬盘、没有 I/O 的 CPU。
- 上下文窗口 = RAM（快但有限）
- 外部数据库 = 硬盘（大但慢）
- 工具集成 = 设备驱动
- Harness = 操作系统
三层工程体系
- 提示词工程：精心制作模型接收的指令
- 上下文工程：管理模型看到什么、何时看到
- Harness 工程：涵盖前两者 + 完整应用基础设施
12个生产级组件
1. 编排循环（Orchestration Loop）
实现 TAO 循环（思考-行动-观察），即 ReAct 循环。
循环流程：组装提示词 → 调用 LLM → 解析输出 → 执行工具调用 → 反馈结果 → 重复直到完成
Anthropic 将其运行时描述为"哑循环"——所有智能都在模型里，harness 只管理回合。
2. 工具（Tools）
工具被定义为模式（名称、描述、参数类型），注入到 LLM 的上下文中。
Claude Code 六类工具：文件操作、搜索、执行、网络访问、代码智能和子智能体生成
3. 记忆（Memory）
- 短期记忆：单个会话内的对话历史
- 长期记忆：跨会话持久化
Claude Code 三层层次结构：
- 轻量级索引（每条约 150 字符，始终加载）
- 按需拉取的详细文件
- 仅通过搜索访问的原始记录
关键设计原则：Agent 把自己的记忆当作"提示"，在行动前会对照实际状态验证。
4. 上下文管理（Context Management）
核心问题：上下文腐烂——关键内容落在窗口中间位置时，模型性能下降 30% 以上。
生产策略：
- 压缩：总结对话历史，保留架构决策和未解决的 bug
- 观察遮蔽：隐藏旧的工具输出，但保持工具调用可见
- 即时检索：使用 grep、glob、head、tail 而不是加载完整文件
- 子智能体委托：每个子智能体广泛探索，但只返回 1000-2000 token 的压缩摘要
5. 提示词构建（Prompt Construction）
分层的组装：系统提示词 → 工具定义 → 记忆文件 → 对话历史 → 当前用户消息
OpenAI Codex 优先级栈：服务器系统消息（最高）→ 工具定义 → 开发者指令 → 用户指令（级联 AGENTS.md）→ 对话历史
6. 输出解析（Output Parsing）
现代 harness 依赖原生工具调用，模型返回结构化的 tool_calls 对象。
检查逻辑：
- 有工具调用？执行并循环
- 没有工具调用？最终答案
7. 状态管理（State Management）
LangGraph 将状态建模为流经图节点的类型化字典，用 reducer 合并更新。检查点发生在超级步骤边界，支持中断后恢复和时间旅行调试。
OpenAI 四种策略：应用程序内存、SDK 会话、服务器端 Conversations API、轻量级 previous_response_id 链接
8. 错误处理（Error Handling）
关键数据：一个 10 步流程，每步 99% 成功率，端到端成功率仍然只有约 90.4%。错误会快速复合。
LangGraph 四种错误类型：
- 瞬态错误：带退避重试
- LLM 可恢复错误：将错误作为 ToolMessage 返回，让模型调整
- 用户可修复错误：中断等待人工输入
- 意外错误：冒泡用于调试
Stripe 将重试尝试上限设为两次。
9. 防护栏和安全（Guardrails and Safety）
OpenAI SDK 三个级别：
- 输入防护栏（在第一个 agent 上运行）
- 输出防护栏（在最终输出上运行）
- 工具防护栏（在每次工具调用时运行）
Anthropic 将权限执行与模型推理分离：模型决定尝试什么，工具系统决定允许什么。
Claude Code 独立管理约 40 个离散工具能力，分三阶段：项目加载时建立信任 → 每次工具调用前权限检查 → 高风险操作明确用户确认
10. 验证循环（Verification Loops）
这是区分玩具演示和生产 agent 的关键。
三种方法：
- 基于规则的反馈：测试、linter、类型检查器
- 视觉反馈：通过 Playwright 截图用于 UI 任务
- LLM 作为评判者：单独的子智能体评估输出
关键洞察：给模型一种验证其工作的方法，质量提高 2 到 3 倍
11. 子智能体编排（Subagent Orchestration）
Claude Code 三种执行模型：
- Fork：父上下文的字节相同副本
- Teammate：带有基于文件的邮箱通信的单独终端窗格
- Worktree：自己的 git 工作树，每个 agent 一个独立分支
OpenAI SDK：智能体作为工具（专家处理有界子任务）和交接（专家获得完全控制）
LangGraph：子智能体实现为嵌套状态图
12. 输出解析 / 状态管理（见上）
单循环工作流
步骤 1（提示词组装）：构建完整输入，重要上下文放在开头和结尾（"Lost in the Middle"发现）
步骤 2（LLM 推理）：组装的提示词发送到模型 API
步骤 3（输出分类）：有工具调用？继续执行。没有？循环结束
步骤 4（工具执行）：验证参数 → 检查权限 → 在沙盒环境中执行
- 只读操作可以并发运行
- 变更操作串行运行
步骤 5（结果打包）：格式化为 LLM 可读消息，错误被捕获并作为错误结果返回
步骤 6（上下文更新）：结果附加到对话历史，接近窗口限制时触发压缩
步骤 7（循环）：返回步骤 1，重复直到终止
终止条件（分层）：
- 模型产生没有工具调用的响应
- 超过最大回合限制
- token 预算耗尽
- 防护栏触发
- 用户中断
- 返回安全拒绝
真实框架实现
Anthropic Claude Agent SDK
通过单个 query() 函数暴露 harness，运行时是"哑循环"，所有智能都在模型里。Claude Code 使用收集-行动-验证循环。
OpenAI Agents SDK
通过 Runner 类实现 harness，三种模式：异步、同步和流式。SDK 是"代码优先"：工作流逻辑用原生 Python 表达。Codex harness 三层：Codex Core、App Server（双向 JSON-RPC API）、客户端界面。
LangGraph
将 harness 建模为显式状态图，两个节点（llm_call 和 tool_node）通过条件边连接。
CrewAI
实现基于角色的多智能体架构：Agent（围绕 LLM 的 harness）、Task（工作单元）、Crew（智能体集合）。Flows 层添加"具有智能的确定性骨干"。
AutoGen（Microsoft）
三层架构（Core、AgentChat、Extensions）支持五种编排模式：顺序、并发（扇出/扇入）、群聊、交接和 magentic（管理器 agent 维护动态任务分类账）
定义 Harness 的七个决策
单智能体 vs. 多智能体 首先最大化单个 agent。多智能体只在工具过载超过约 10 个重叠工具或存在明显独立任务域时才拆分。
ReAct vs. 计划-执行 ReAct 在每一步交织推理和行动（灵活但每步成本更高）。计划-执行将规划与执行分离。LLMCompiler 报告比顺序 ReAct 快 3.6 倍。
上下文窗口管理策略 五种方法：基于时间的清除、对话总结、观察遮蔽、结构化笔记、子智能体委托。ACON 研究显示 token 减少 26-54%，同时保持 95% 以上准确性。
验证循环设计
- 计算验证：确定性真相
- 推理验证：捕获语义问题但增加延迟
- 可分为前馈（行动前引导）和传感器（行动后观察）
权限和安全架构
- 宽松（快但有风险，自动批准大多数操作）
- 限制性（安全但慢，每个操作都需要批准）
工具范围策略 更多工具通常意味着更差的性能。Vercel 从 v0 中删除了 80% 的工具，获得了更好的结果。Claude Code 通过延迟加载实现 95% 的上下文减少。
原则：暴露当前步骤所需的最小工具集
Harness 厚度 Anthropic 押注于薄 harness 和模型改进。基于图的框架押注于显式控制。
脚手架隐喻与协同进化
建筑脚手架是临时基础设施，使工人能够建造他们无法触及的结构。它不做建造，但没有它，工人无法到达上层。建筑完成后，脚手架会被拆除。
随着模型改进，harness 复杂性应该降低。Manus 在六个月内重建了五次，每次重写都删除了复杂性。
Harness 设计的"未来验证测试"：如果性能随着更强大的模型扩展而不增加 harness 复杂性，设计就是合理的。
结论
使用相同模型的两个产品，仅基于 harness 设计就可以有截然不同的性能。TerminalBench 的证据很清楚：仅改变 harness 就使 agent 移动了 20+ 个排名位置。
Harness 不是已解决的问题或商品层。这是艰苦工程的所在：
- 将上下文作为稀缺资源管理
- 设计在失败复合之前捕获失败的验证循环
- 构建提供连续性而不产生幻觉的记忆系统
- 在构建多少脚手架与留给模型多少之间做出架构押注
该领域正朝着更薄的 harness 发展，因为模型在改进。但 harness 本身不会消失。即使是最有能力的模型也需要：管理上下文窗口、执行工具调用、持久化状态、验证工作。
一句话总结
"如果你不是模型，你就是 harness"