深度拆解：AI Agent Harness 的构造 · AI HOT
宝玉@dotey57
2026-05-11 06:23·53天前
AI 摘要文章指出，将大语言模型转化为可靠智能体的关键在于其外围基础设施，即“AI Agent Harness”。它被定义为产生智能体行为的完整软件架构，包括编排循环、工具、记忆、上下文管理等核心组件。这如同操作系统之于CPU，是智能体得以自主运行的“机器”。Harness工程超越了提示词工程，涵盖了完整的应用架构，是解决智能体在生产环境中表现不稳定的根本方案。
宝玉@dotey · X 2026-05-11 06:23·53天前
在 X 看原推· x.comAI 摘要文章指出，将大语言模型转化为可靠智能体的关键在于其外围基础设施，即“AI Agent Harness”。它被定义为产生智能体行为的完整软件架构，包括编排循环、工具、记忆、上下文管理等核心组件。这如同操作系统之于CPU，是智能体得以自主运行的“机器”。Harness工程超越了提示词工程，涵盖了完整的应用架构，是解决智能体在生产环境中表现不稳定的根本方案。
Claude Code 实现了三层记忆架构：一个轻量级索引（每条约 150 字符，始终加载）、按需调用的详细主题文件，以及仅通过搜索访问的原始对话记录。一个核心设计原则是：智能体将自己的记忆视为一种"提示"，在行动前必须根据实际状态进行验证。
4. 上下文管理 （Context Management）
这是许多智能体容易暗中翻车的地方。核心问题在于上下文腐烂：当关键信息处于窗口中间位置时，模型表现会下降 30% 以上（这就是斯坦福大学发现的"迷失在中间"现象）。即便是支持百万级 Token （Token：模型处理文本的最小单位，大致相当于单词或汉字的部分） 的窗口，随着上下文的增长，指令遵循能力也会退化。
- 压缩 （Compaction）：在接近限制时总结对话历史（Claude Code 会保留架构决策和未修复的 Bug，同时丢弃冗余的工具输出）。
- 观察掩码 （Observation masking）：隐藏旧的工具输出，但保留工具调用的记录。
- 即时检索 （Just-in-time retrieval）：只保留轻量级标识符，动态加载数据（Claude Code 倾向于使用 grep 或 head 命令，而不是加载整个文件）。
- 子智能体委托：让每个子智能体进行深度探索，但仅返回 1000 到 2000 Token 的浓缩摘要。
Anthropic 的上下文工程指南指出，目标是：找到能最大化达成目标概率的、信号最强的最小 Token 集合。
5. 提示词构建 （Prompt Construction）
这决定了模型在每一步具体能看到什么。它是层级化的：系统提示词、工具定义、记忆文件、对话历史，以及当前的用户消息。
OpenAI 的 Codex 使用严格的优先级栈：服务器控制的系统消息（最高优先级）、工具定义、开发者指令、用户指令，最后才是对话历史。
6. 输出解析 （Output Parsing）
现代 Harness 依赖于原生工具调用，即模型返回结构化的 tool_calls 对象，而不是需要费力解析的自由文本。Harness 会检查：是否有工具调用？如果有，执行并继续循环；如果没有，那当前的输出就是最终答案。
对于结构化输出，OpenAI 和 LangChain 都支持通过 Pydantic 模型 （Python 中用于数据校验和格式化的库） 进行模式约束。
7. 状态管理 （State Management）
LangGraph 将状态模拟为在图形节点中流动的类型化字典。系统会在关键步骤进行"存档"（Checkpointing），这样即使中断也能恢复，甚至可以进行"时间旅行"式的调试。OpenAI 则提供了四种策略：应用内存、SDK 会话、服务器端 API 或轻量级的响应 ID 链。Claude Code 采用了不同的思路：将 Git 提交作为存档点，将进度文件作为结构化的草稿纸。
8. 错误处理 （Error Handling）
为什么这很重要？一个包含 10 个步骤的过程，即使每一步的成功率高达 99%，最终全流程的成功率也只有约 90.4%。错误是会滚雪球的。
LangGraph 将错误分为四类：临时性的（带延迟的重试）、模型可恢复的（将错误作为工具消息返回，让模型自己调整）、用户可修复的（暂停等待人类干预）以及意外错误（上报调试）。
9. 护栏与安全 （Guardrails and Safety）
OpenAI 的 SDK 实现了三个层级：输入护栏（在第一个智能体运行时检查）、输出护栏（检查最终结果）以及工具护栏（每次调用工具前检查）。一旦触发"绊网"（Tripwire）机制，智能体将立即停止。
Anthropic 在架构上将"权限执行"与"模型推理"分离。模型决定想做什么，但 Harness 决定允许做什么。
10. 验证循环 （Verification Loops）
这是区分"玩具演示"和"生产级智能体"的关键。Anthropic 推荐三种方法：基于规则的反馈（测试、代码检查）、视觉反馈（通过 Playwright 截取 UI 截图）以及以大语言模型为裁判 （LLM-as-judge）（由另一个子智能体评估输出）。
Claude Code 的创造者 Boris Cherny 指出，让模型能够验证自己的工作，能让产出质量提升 2 到 3 倍。
11. 子智能体编排 （Subagent Orchestration）
Claude Code 支持三种模式：克隆 （Fork）（复制父级上下文）、队友 （Teammate）（通过文件邮箱通信的独立窗口）和 工作树 （Worktree）（独立的 Git 分支）。OpenAI 则支持将智能体作为工具（专家处理特定子任务）或移交（专家接管后续控制权）。
既然了解了组件，让我们看看它们在一次循环中是如何协同工作的。
- 第一步（提示词组装）：Harness 构建完整的输入信息。
- 第二步（模型推理）：组装好的内容发送给模型 API，模型生成 Token：可能是文本，也可能是工具调用请求。
- 第三步（输出分类）：如果没有工具调用，循环结束；如果有，进入执行阶段。
- 第四步（工具执行）：Harness 校验参数、检查权限，在沙箱中运行并捕获结果。
- 第五步（结果打包）：将结果格式化为模型可读的消息，捕获错误以便模型自愈。
- 第六步（上下文更新）：将结果追加到历史记录，必要时触发压缩。
- Anthropic （Claude Agent SDK）：通过一个简单的 query（） 函数暴露 Harness，运行时是一个"笨循环"，智慧全在模型里。
- OpenAI （Agents SDK）：采用"代码优先"策略，工作流逻辑直接用 Python 表达，而不是复杂的图形语言。
- LangGraph：将 Harness 建模为显式的状态图，强调对流程的精细控制。
- CrewAI：实现了基于角色的多智能体协作，由"流程层"管理确定性的骨干逻辑。
- AutoGen：由微软开发，支持多种编排模式，如顺序执行、群聊、移交和动态任务管理。
"脚手架"这个比喻并非装饰，而是极其精准的。建筑脚手架是临时性的基础设施，让工人们能触及原本够不到的高度。脚手架本身不盖房子，但没有它，工人就上不去高层。
关键洞察在于：房子盖好后，脚手架是要拆除的。 随着模型能力的提升，Harness 的复杂程度应该逐渐降低。
这就是协同进化原则：现在的模型在训练时，就已经考虑了 Harness 的存在。如果你的 Harness 设计得好，当模型升级时，你不需要增加复杂度，性能就会自动提升。
- 单智能体 vs. 多智能体：官方建议：先充分挖掘单智能体的潜力。多智能体会带来额外的开销和信息损耗。
- ReAct vs. 先规划后执行：ReAct 灵活但成本高；"先规划后执行"速度更快。
- 验证循环设计：是用硬性的代码测试，还是用另一个 LLM 来打分？
- 权限与安全架构：是追求速度自动批准，还是追求安全步步确认？
- 工具范围管理：工具不是越多越好。暴露当前步骤所需的最小工具集往往效果最佳。
- Harness 的厚度：多少逻辑写死在系统里，多少逻辑留给模型发挥？
两个使用完全相同模型的智能体，性能可能天差地别，原因就在于 Harness 的设计。TerminalBench 的证据已经非常明确：仅仅改变 Harness，就能让排名变动 20 多位。
Harness 不是一个已经解决的问题，也不是一个通用的商品层。它是硬核工程能力的体现：如何将上下文视为稀缺资源进行管理？如何设计验证循环以防止错误累积？如何构建不产生幻觉的记忆系统？
随着模型越来越强，Harness 会变薄，但它永远不会消失。即便最强大的模型，也需要系统来管理窗口、执行代码、保存状态并验证工作。
下次当你的智能体表现不佳时，别光顾着抱怨模型，去检查一下你的Harness吧。
如果你喜欢这些内容： 关注我 → https://x.com/@akshay_pachaar ✔️ 每天我都会分享关于 AI、机器学习和凭感觉编程 （Vibe Coding） 最佳实践的教程与见解。
我非常喜欢 LangChain 的 Vivek Trivedy 给出的定义公式："如果你不是模型本身，那你就是 Harness。"
这里有一个经常让人搞混的区别："AI 智能体"（Agent）是用户感知到的行为体现，它是一个有目标、会用工具、能自我纠错的实体；而"Harness"则是产生这种行为的背后机器。当有人说"我开发了一个智能体"时，他真正的意思是"我开发了一套 Harness，并把它接入了模型"。
Beren Millidge 在其 2023 年的博文中做了一个精准的类比：原生大语言模型就像一个没有内存、没有硬盘、也没有输入输出设备的 CPU。此时，上下文窗口充当了内存（快但容量有限），外部数据库扮演了硬盘（大但速度慢），工具集成则是设备驱动程序。而Harness，就是那个操作系统。正如 Millidge 所写："我们重新发明了冯·诺依曼架构（Von Neumann architecture）"，因为这是任何计算系统最自然的抽象方式。
- 提示词工程 （Prompt engineering）：精心设计模型接收到的指令。
- 上下文工程 （Context engineering）：管理模型在什么时间点能看到什么内容。
- Harness 工程 （Harness engineering）：涵盖了上述两者，再加上整个应用架构：包括工具编排、状态持久化、错误恢复、验证循环、安全执行以及生命周期管理。
Harness 不仅仅是一个包裹提示词的套壳（AI Wrapper），它是让智能体能够自主行动的完整系统。
综合 Anthropic、OpenAI、LangChain 以及广大从业者的实践经验，一个生产级的 Agent Harness 由 12 个不同的组件构成。让我们逐一拆解。
1. 编排循环 （The Orchestration Loop）
这是系统的"心脏"。它实现了"思考 - 行动 - 观察"（Thought-Action-Observation，简称 TAO）循环，也被称为 ReAct 循环。这个循环不停运转：整合提示词 -> 调用大语言模型 -> 解析输出 -> 执行工具调用 -> 反馈结果 -> 重复，直到任务完成。
从技术实现上看，它通常只是一个 while 循环。但复杂的地方不在于循环本身，而在于循环所要处理的各种状态和逻辑。Anthropic 将他们的运行时描述为一个"笨循环"，所有的智慧都存在于模型之中，Harness 只负责管理回合的切换。
2. 工具 （Tools）
工具是智能体的"双手"。它们被定义为某种结构化模式（名称、描述、参数类型），并注入到模型的上下文中，让模型知道哪些工具可用。工具层负责注册、格式校验、参数提取、在沙箱（Sandbox）环境执行、结果捕获，并最终将结果格式化为模型可读的"观察结果"。
Claude Code 提供了六大类工具：文件操作、搜索、执行、网页访问、代码分析和子智能体创建。OpenAI 的 Agents SDK 则支持函数工具（通过 @function_tool 定义）、托管工具（如网页搜索、代码解释器、文件搜索）以及 MCP （Model Context Protocol，一种开放的工具接入标准） 服务器工具。
3. 记忆 （Memory）
记忆在不同的时间尺度上运作。短期记忆是单次会话中的对话历史。长期记忆则跨越多个会话持久存在：Anthropic 使用项目文件和自动生成的 memory.md 文件；LangGraph 使用按命名空间组织的 JSON 存储；OpenAI 则支持由 SQLite 或 Redis 驱动的会话存储。
Claude Code 实现了三层记忆架构：一个轻量级索引（每条约 150 字符，始终加载）、按需调用的详细主题文件，以及仅通过搜索访问的原始对话记录。一个核心设计原则是：智能体将自己的记忆视为一种"提示"，在行动前必须根据实际状态进行验证。
4. 上下文管理 （Context Management）
这是许多智能体容易暗中翻车的地方。核心问题在于上下文腐烂：当关键信息处于窗口中间位置时，模型表现会下降 30% 以上（这就是斯坦福大学发现的"迷失在中间"现象）。即便是支持百万级 Token （Token：模型处理文本的最小单位，大致相当于单词或汉字的部分） 的窗口，随着上下文的增长，指令遵循能力也会退化。
- 压缩 （Compaction）：在接近限制时总结对话历史（Claude Code 会保留架构决策和未修复的 Bug，同时丢弃冗余的工具输出）。
- 观察掩码 （Observation masking）：隐藏旧的工具输出，但保留工具调用的记录。
- 即时检索 （Just-in-time retrieval）：只保留轻量级标识符，动态加载数据（Claude Code 倾向于使用 grep 或 head 命令，而不是加载整个文件）。
- 子智能体委托：让每个子智能体进行深度探索，但仅返回 1000 到 2000 Token 的浓缩摘要。
Anthropic 的上下文工程指南指出，目标是：找到能最大化达成目标概率的、信号最强的最小 Token 集合。
5. 提示词构建 （Prompt Construction）
这决定了模型在每一步具体能看到什么。它是层级化的：系统提示词、工具定义、记忆文件、对话历史，以及当前的用户消息。
OpenAI 的 Codex 使用严格的优先级栈：服务器控制的系统消息（最高优先级）、工具定义、开发者指令、用户指令，最后才是对话历史。
6. 输出解析 （Output Parsing）
现代 Harness 依赖于原生工具调用，即模型返回结构化的 tool_calls 对象，而不是需要费力解析的自由文本。Harness 会检查：是否有工具调用？如果有，执行并继续循环；如果没有，那当前的输出就是最终答案。
对于结构化输出，OpenAI 和 LangChain 都支持通过 Pydantic 模型 （Python 中用于数据校验和格式化的库） 进行模式约束。
7. 状态管理 （State Management）
LangGraph 将状态模拟为在图形节点中流动的类型化字典。系统会在关键步骤进行"存档"（Checkpointing），这样即使中断也能恢复，甚至可以进行"时间旅行"式的调试。OpenAI 则提供了四种策略：应用内存、SDK 会话、服务器端 API 或轻量级的响应 ID 链。Claude Code 采用了不同的思路：将 Git 提交作为存档点，将进度文件作为结构化的草稿纸。
8. 错误处理 （Error Handling）
为什么这很重要？一个包含 10 个步骤的过程，即使每一步的成功率高达 99%，最终全流程的成功率也只有约 90.4%。错误是会滚雪球的。
LangGraph 将错误分为四类：临时性的（带延迟的重试）、模型可恢复的（将错误作为工具消息返回，让模型自己调整）、用户可修复的（暂停等待人类干预）以及意外错误（上报调试）。
9. 护栏与安全 （Guardrails and Safety）
OpenAI 的 SDK 实现了三个层级：输入护栏（在第一个智能体运行时检查）、输出护栏（检查最终结果）以及工具护栏（每次调用工具前检查）。一旦触发"绊网"（Tripwire）机制，智能体将立即停止。
Anthropic 在架构上将"权限执行"与"模型推理"分离。模型决定想做什么，但 Harness 决定允许做什么。
10. 验证循环 （Verification Loops）
这是区分"玩具演示"和"生产级智能体"的关键。Anthropic 推荐三种方法：基于规则的反馈（测试、代码检查）、视觉反馈（通过 Playwright 截取 UI 截图）以及以大语言模型为裁判 （LLM-as-judge）（由另一个子智能体评估输出）。
Claude Code 的创造者 Boris Cherny 指出，让模型能够验证自己的工作，能让产出质量提升 2 到 3 倍。
11. 子智能体编排 （Subagent Orchestration）
Claude Code 支持三种模式：克隆 （Fork）（复制父级上下文）、队友 （Teammate）（通过文件邮箱通信的独立窗口）和 工作树 （Worktree）（独立的 Git 分支）。OpenAI 则支持将智能体作为工具（专家处理特定子任务）或移交（专家接管后续控制权）。
既然了解了组件，让我们看看它们在一次循环中是如何协同工作的。
- 第一步（提示词组装）：Harness 构建完整的输入信息。
- 第二步（模型推理）：组装好的内容发送给模型 API，模型生成 Token：可能是文本，也可能是工具调用请求。
- 第三步（输出分类）：如果没有工具调用，循环结束；如果有，进入执行阶段。
- 第四步（工具执行）：Harness 校验参数、检查权限，在沙箱中运行并捕获结果。
- 第五步（结果打包）：将结果格式化为模型可读的消息，捕获错误以便模型自愈。
- 第六步（上下文更新）：将结果追加到历史记录，必要时触发压缩。
- Anthropic （Claude Agent SDK）：通过一个简单的 query（） 函数暴露 Harness，运行时是一个"笨循环"，智慧全在模型里。
- OpenAI （Agents SDK）：采用"代码优先"策略，工作流逻辑直接用 Python 表达，而不是复杂的图形语言。
- LangGraph：将 Harness 建模为显式的状态图，强调对流程的精细控制。
- CrewAI：实现了基于角色的多智能体协作，由"流程层"管理确定性的骨干逻辑。
- AutoGen：由微软开发，支持多种编排模式，如顺序执行、群聊、移交和动态任务管理。
"脚手架"这个比喻并非装饰，而是极其精准的。建筑脚手架是临时性的基础设施，让工人们能触及原本够不到的高度。脚手架本身不盖房子，但没有它，工人就上不去高层。
关键洞察在于：房子盖好后，脚手架是要拆除的。 随着模型能力的提升，Harness 的复杂程度应该逐渐降低。
这就是协同进化原则：现在的模型在训练时，就已经考虑了 Harness 的存在。如果你的 Harness 设计得好，当模型升级时，你不需要增加复杂度，性能就会自动提升。
- 单智能体 vs. 多智能体：官方建议：先充分挖掘单智能体的潜力。多智能体会带来额外的开销和信息损耗。
- ReAct vs. 先规划后执行：ReAct 灵活但成本高；"先规划后执行"速度更快。
- 验证循环设计：是用硬性的代码测试，还是用另一个 LLM 来打分？
- 权限与安全架构：是追求速度自动批准，还是追求安全步步确认？
- 工具范围管理：工具不是越多越好。暴露当前步骤所需的最小工具集往往效果最佳。
- Harness 的厚度：多少逻辑写死在系统里，多少逻辑留给模型发挥？
两个使用完全相同模型的智能体，性能可能天差地别，原因就在于 Harness 的设计。TerminalBench 的证据已经非常明确：仅仅改变 Harness，就能让排名变动 20 多位。
Harness 不是一个已经解决的问题，也不是一个通用的商品层。它是硬核工程能力的体现：如何将上下文视为稀缺资源进行管理？如何设计验证循环以防止错误累积？如何构建不产生幻觉的记忆系统？
随着模型越来越强，Harness 会变薄，但它永远不会消失。即便最强大的模型，也需要系统来管理窗口、执行代码、保存状态并验证工作。
下次当你的智能体表现不佳时，别光顾着抱怨模型，去检查一下你的Harness吧。
如果你喜欢这些内容： 关注我 → https://x.com/@akshay_pachaar ✔️ 每天我都会分享关于 AI、机器学习和凭感觉编程 （Vibe Coding） 最佳实践的教程与见解。