深度拆解：AI Agent Harness 的构造

Harness 是包裹在大语言模型之外的完整软件架构：编排循环、工具、记忆、上下文管理、状态持久化、错误处理、护栏。Anthropic 在 Claude Code 文档里直接说：SDK 就是「驱动 Claude Code 的 Agent Harness」。OpenAI Codex 团队也把「智能体」与「Harness」等同于让 LLM 真正干活的非模型架构。

LangChain 的 Vivek Trivedy 有句好记的话：「如果你不是模型本身，那你就是 Harness。」

容易混的一点：

• Agent 是用户感知到的行为体——有目标、会用工具、能自纠。
• Harness 是产生这种行为的机器。
  说「我做了一个智能体」，真实意思多半是「我做了一套 Harness，并接上了模型」。

Beren Millidge 的类比：原生 LLM 像没有内存、硬盘与 I/O 的 CPU；上下文窗口是内存，外部库是硬盘，工具是驱动，Harness 是操作系统。工程上可以看成三个同心圆：

1. 提示词工程 —— 模型收到什么指令
2. 上下文工程 —— 何时能看到什么
3. Harness 工程 —— 两者 + 工具编排、状态、错误恢复、验证、安全执行、生命周期

1. 编排循环

系统心脏：Thought–Action–Observation（或 ReAct）while 循环——拼提示 → 调模型 → 解析 → 执行工具 → 反馈 → 直到完成。难的不是循环本身，是循环里的状态与边界。Anthropic 称自己的 runtime 是「笨循环」：智慧在模型，Harness 只管回合切换。

2. 工具（Tools）

智能体的「双手」。结构化 schema（名、描述、参数）注入上下文；工具层负责注册、校验、沙箱执行、结果回写。这是 工具调用 的完整生命周期，而不只是「模型吐了一个 JSON」。Claude Code 有文件、搜索、执行、网页、代码分析、子智能体等大类；OpenAI Agents SDK 有函数工具、托管工具与 MCP 服务器工具。

3. 记忆（Memory）

短期是会话历史；长期跨会话持久化——这是 记忆系统 的双轨。Claude Code 三层：轻量索引（始终加载）、按需主题文件、可搜索原始对话。原则：把记忆当提示，行动前用真实状态再验证。

4. 上下文管理

暗坑最多的地方。上下文腐烂、Lost-in-the-Middle、窗口变大但指令遵循退化，都在这里发生。生产策略：

• 压缩（Compaction）：接近上限时总结，保留架构决策与未修 bug
• 观察掩码：藏旧工具输出，保留调用记录
• 即时检索：只留标识符，动态 grep / head
• 子智能体委托：深探后只回 1k–2k token 摘要

目标：最大化达成目标概率的、信号最强的最小 token 集。

5. 提示词构建

层级栈：系统提示、工具定义、记忆、对话史、当前用户消息。OpenAI Codex 有严格优先级：服务器系统消息 > 工具 > 开发者指令 > 用户指令 > 历史。

6. 输出解析

现代路径靠原生 tool_calls，而不是正则抠自由文本。有工具调用则执行并继续；没有则当最终答案。结构化输出可用 schema 约束。

7. 状态管理

LangGraph 用类型化状态在图节点间流动，关键步骤 checkpoint，可恢复甚至「时间旅行」。OpenAI 有内存 / SDK 会话 / 服务端 API / 响应 ID 链等策略。Claude Code 常把 Git 提交当存档点、进度文件当草稿纸。

8. 错误处理

10 步、每步 99% 成功，全流程约 90%。LangGraph 四类：临时可重试、模型可恢复（错误当工具消息）、用户可修复（暂停）、意外上报。

9. 护栏与安全

OpenAI 三层：输入、输出、工具调用前。触发 tripwire 立即停。Anthropic 把权限执行与模型推理拆开：模型决定想做什么，Harness 决定允许做什么。更激进的做法是用状态机把「当前 phase 可用工具」变成硬约束，而不是只靠系统提示劝说——与 状态机护栏 同一思路。

10. 验证循环

玩具与生产的分水岭。规则反馈（测试、lint）、视觉反馈（UI 截图）、LLM-as-judge。Boris Cherny 称：让模型能验证自己的工作，质量可提升 2–3 倍。

11. 子智能体编排

当单循环不够时，进入 多智能体 编排。Claude Code：Fork（复制父上下文）、Teammate（文件邮箱）、Worktree（独立分支）。OpenAI：智能体当工具，或 handoff 移交控制权。默认建议仍是：先榨干单智能体，再引入多角色。

12. 生命周期与退出

何时结束、如何汇总、如何对人类交付——常被省略，却是用户体感的关键一环。

1. 提示词组装
2. 模型推理
3. 输出分类（有无 tool call）
4. 工具执行（校验、权限、沙箱）
5. 结果打包（错误也可回传自愈）
6. 上下文更新（必要时压缩）
7. 循环直至退出

| 体系 | 取向 | | --- | --- | | Anthropic Claude Agent SDK | query() 暴露 Harness；笨循环，智慧在模型 | | OpenAI Agents SDK | 代码优先，工作流用 Python 表达 | | LangGraph | 显式状态图，精细控制 | | CrewAI | 角色多智能体 + 确定性流程层 | | AutoGen | 顺序、群聊、移交、动态任务 |

脚手架盖好房子后要拆。模型变强，Harness 应变薄，而不是无限加厚——这是协同进化：现在的模型训练时已考虑 Harness 的存在。Harness 设计得好，模型升级时性能自动抬升，不必堆复杂度。

1. 单智能体 vs 多智能体 —— 先榨干单智能体；多智能体有开销与信息损耗。
2. ReAct vs 先规划后执行 —— 灵活 vs 成本/速度。
3. 上下文策略 —— 总结 vs 动态加载。
4. 验证循环 —— 硬测试 vs LLM 裁判。
5. 权限架构 —— 自动批准 vs 步步确认。
6. 工具范围 —— 最小必要工具集往往更好。
7. Harness 厚度 —— 多少逻辑写死，多少留给模型。

同一模型、不同 Harness，性能可差几十名。TerminalBench 已证明：只改 Harness 就能大幅换排名。

1. 先画你的循环：提示组装 → 推理 → 工具 → 观察 → 压缩/退出。缺哪一步就补哪一步，而不是先上多智能体框架。
2. 把权限与推理拆开：模型可以「想」危险动作，执行层必须能否决。
3. 给验证预算：测试、截图、judge 至少选一种写进默认路径；否则演示成功、生产漂移。
4. 把领域流程做成 Skills，而不是塞进无限系统提示：路由描述 + 渐进加载，避免上下文税爆炸。
5. 记录失败类型：临时 / 可自愈 / 需人 / 意外——对应不同恢复策略。

• Agent 差，先查 Harness，别只怪模型。
• 上下文是稀缺资源；验证循环防错误滚雪球；记忆必须可校验。
• 模型越强，Harness 越薄，但不会消失：仍要管窗口、执行、状态、验证。
• 「脚手架最终可拆」是方向，不是借口：在模型还不够稳的今天，厚度与可观测性仍然值钱。