Table of contents
Open Table of contents
什么是 Agent Harness
Harness 是包裹在大语言模型之外的完整软件架构，包括编排循环、工具、记忆、上下文管理、状态持久化、错误处理和护栏。Anthropic 在 Claude Code 文档中直指 SDK 就是”驱动 Claude Code 的 Agent Harness”。OpenAI Codex 团队同样将 Agent 和 Harness 等同。
LangChain 的 Vivek Trivedy 的定义公式：“如果你不是模型本身，那你就是 Harness。”
关键区分：AI Agent 是用户感知的行为体现（有目标、用工具、自我纠错），Harness 是产生这些行为的背后机器。
类比：LLM 是 CPU，Harness 是操作系统
Beren Millidge (2023) 的类比：
- 上下文窗口 = 内存（快但容量有限）
- 外部数据库 = 硬盘（大但慢）
- 工具集成 = 设备驱动程序
- Harness = 操作系统
“我们重新发明了冯·诺依曼架构。“
工程化三层次
| 层次 | 内容 |
|---|---|
| 提示词工程 | 精心设计模型接收的指令 |
| 上下文工程 | 管理模型在什么时间点看到什么内容 |
| Harness 工程 | 涵盖上述两者 + 工具编排、状态持久化、错误恢复、验证循环、安全执行、生命周期管理 |
Harness 不仅仅是提示词的套壳，它是让 Agent 自主行动的完整系统。
12 个核心组件
1. 编排循环
系统的”心脏”。实现思考-行动-观察（TAO/ReAct）循环：整合提示词 → 调用 LLM → 解析输出 → 执行工具 → 反馈结果 → 重复，直到任务完成。本质是一个 while 循环，复杂的是循环要处理的状态和逻辑。Anthropic 将其描述为”笨循环”，智慧全在模型里。
2. 工具
Agent 的”双手”。结构化模式（名称、描述、参数类型）注入模型上下文，负责注册、校验、参数提取、沙箱执行、结果捕获。Claude Code 提供六大类工具：文件操作、搜索、执行、网页访问、代码分析和子 Agent 创建。OpenAI Agents SDK 支持函数工具、托管工具和 MCP 服务器工具。
3. 记忆
三层时间尺度：
- 短期记忆：单次会话的对话历史
- 长期记忆：跨会话持久化（项目文件、memory.md、JSON 存储、SQLite/Redis 会话存储）
Claude Code 实现：轻量索引（~150 字符，始终加载）→ 按需调用的详细主题文件 → 仅搜索访问的原始对话记录。核心原则：Agent 将记忆视为”提示”，行动前必须根据实际状态验证。
4. 上下文管理
核心问题：上下文腐烂——关键信息在窗口中间时模型表现下降 30%+（“迷失在中间”现象）。即使百万 token 窗口，指令遵循能力也随上下文增长退化。
应对策略：
- 压缩：接近限制时总结对话历史
- 观察掩码：隐藏旧工具输出，保留工具调用记录
- 即时检索：保留轻量标识符，动态加载数据
- 子 Agent 委托：深度探索后仅返回 1000-2000 token 浓缩摘要
目标：找到信号最强的、能最大化目标达成概率的最小 token 集合。
5. 提示词构建
层级化组装：系统提示词 → 工具定义 → 记忆文件 → 对话历史 → 当前用户消息。OpenAI Codex 使用严格优先级栈。
6. 输出解析
现代 Harness 依赖原生工具调用（结构化 tool_calls 对象而非自由文本）。检查是否有工具调用 → 有则执行并继续循环 → 无则是最终答案。结构化输出通过 Pydantic 模型进行模式约束。
7. 状态管理
- LangGraph：类型化字典流经图节点，关键步骤存档（Checkpointing），支持中断恢复和”时间旅行”调试
- OpenAI：四种策略（应用内存、SDK 会话、服务端 API、响应 ID 链）
- Claude Code：Git 提交作为存档点，进度文件作为结构化草稿纸
8. 错误处理
10 步过程每步 99% 成功率 → 全流程仅 90.4%。错误会滚雪球。
LangGraph 四类错误：临时性（延迟重试）、模型可恢复（将错误作为工具消息让模型调整）、用户可修复（暂停等人工干预）、意外错误（上报调试）。
9. 护栏与安全
OpenAI SDK 三级护栏：输入护栏（首次运行前检查）→ 输出护栏（检查最终结果）→ 工具护栏（每次调用前检查）。触发绊网立即停止。
Anthropic 将权限执行与模型推理分离：模型决定想做什么，Harness 决定允许做什么。
10. 验证循环
区分”玩具演示”和”生产级 Agent”的关键。三种方法：
- 基于规则反馈（测试、代码检查）
- 视觉反馈（Playwright 截取 UI 截图）
- LLM-as-judge（另一个子 Agent 评估输出）
Claude Code 创建者 Boris Cherny：让模型验证自己工作，产出质量提升 2-3 倍。
11. 子 Agent 编排
- Claude Code 三种模式：克隆（复制父级上下文）、队友（文件邮箱通信）、工作树（独立 Git 分支）
- OpenAI：Agent 作为工具（专家处理子任务）或移交（专家接管后续控制权）
12. 循环步进式流程
- 提示词组装 → 2. 模型推理 → 3. 输出分类（无工具调用则结束）→ 4. 工具执行（校验、权限、沙箱）→ 5. 结果打包 → 6. 上下文更新（必要时压缩）→ 7. 返回步骤 1
主流框架实现对比
| 框架 | 策略 |
|---|---|
| Anthropic (Claude Agent SDK) | 通过 query() 暴露 Harness，“笨循环”，智慧在模型 |
| OpenAI (Agents SDK) | 代码优先，工作流用 Python 直接表达 |
| LangGraph | 显式状态图，精细流程控制 |
| CrewAI | 基于角色的多 Agent 协作，流程层管理确定性逻辑 |
| AutoGen (微软) | 多种编排模式：顺序执行、群聊、移交、动态任务管理 |
脚手架比喻
建筑脚手架是临时基础设施，让工人触及原本够不到的高度。脚手架本身不盖房子，但没它工人上不去高层。
关键洞察：房子盖好后，脚手架要拆除。 随着模型能力提升，Harness 复杂度应逐渐降低。
协同进化原则：现在模型训练时已考虑 Harness 的存在。Harness 设计得好，模型升级时不需要增加复杂度，性能自动提升。
7 个关键设计决策
- 单 Agent vs 多 Agent：先充分挖掘单 Agent 潜力。多 Agent 带来额外开销和信息损耗
- ReAct vs 先规划后执行：ReAct 灵活但成本高，先规划后执行更快
- 上下文管理策略：总结 vs 动态加载
- 验证循环设计：硬性代码测试 vs LLM 打分
- 权限与安全架构：速度优先自动批准 vs 安全优先步步确认
- 工具范围：暴露当前步骤所需的最小工具集往往效果最佳
- Harness 厚度：多少逻辑写死在系统，多少留给模型发挥
核心结论
两个使用相同模型的 Agent 性能天差地别，原因全在 Harness 设计。TerminalBench 证据：仅仅改变 Harness，排名可变 20 多位。LangChain 仅改变底层架构就让排名从 30+ 飙升至第 5。
Harness 不是已解决的问题。它是硬核工程能力的体现：如何管理上下文这一稀缺资源？如何设计验证循环防止错误累积？如何构建不产生幻觉的记忆系统？模型越强，Harness 越薄，但永远不会消失——即便最强模型也需要系统来管理窗口、执行代码、保存状态和验证工作。