万字讲透Agent Harness的十二大模块

万字讲透Agent Harness的十二大模块 万字讲透Agent Harness的十二大模块 Modified April 19 步骤 1（提示词组装） ：Harness 构建完整的输入： 系统提示词 (system prompt) + 工具模式 (tool schemas) + 记忆文件 + 对话历史 + 当前用户消息。重要的上下文会被放置在提示词的开头和结尾（这就是著名的"中间迷失"现象）。 步骤 2（LLM 推理） ：组装好的提示词被送往模型 API。模型生成输出 token：可能是纯文本、工具调用请求，或两者兼有。 步骤 3（输出分类） ：如果模型只生成了文本而没有工具调用，循环结束。如果请求了工具调用，则进入执行阶段。如果请求了交接，则更新当前 Agent 并重启。 步骤 4（工具执行） ：对于每个工具调用，Harness 会验证参数、检查权限、在沙箱环境中执行，并捕获结果。只读操作可以并发执行；写操作则串行处理。 步骤 5（结果打包） ：工具结果被格式化为 LLM 可读的消息。错误会被捕获并作为错误结果返回，让模型能够自我修正。 步骤 6（上下文更新） ：结果被追加到对话历史中。如果接近 上下文窗口 (context window) 上限，Harness 会触发压缩。 步骤 7（循环） ：回到步骤 1。重复直到终止。 终止条件是多层级的：模型产出了没有工具调用的回复、达到最大轮次限制、 token 预算耗尽、护栏绊线被触发、用户主动中断、或返回了安全拒绝。一个简单问题可能只需 1 到 2 轮。一个复杂的重构任务则可能跨越多轮，串联数十个工具调用。 示例工作流 ： 初始化 Agent (Initializer Agent) 先搭建环境（初始化脚本、进度文件、功能列表、首次 git 提交），然后每个后续会话中的 编码 Agent (Coding Agent) 会读取 git 日志和进度文件来定位自己，挑选最高优先级的未完成特性，开始工作，提交代码，并撰写摘要。文件系统跨越上下文窗口，提供了连续性。 Agent 执行周期 Anthropic 的 Claude Agent SDK 通过一个 query() 函数暴露出整个 智能体框架 (harness) ，这个函数创建了智能体循环，并返回一个异步迭代器来流式传输消息。运行时就是一个"傻循环"——所有的智商都在模型里。Claude Code 采用了一个 收集 执行 验证 (Gather Act Verify) 的循环： 收集上下文 (gather context) （搜索文件、读取代码）、 采取行动 (take action) （编辑文件、运行命令）、 验证结果 (verify results) （跑测试、检查输出），然后周而复始。 OpenAI 的 Agents SDK 则通过 Runner 类来实现这个框架，提供三种模式：异步 (async)、同步 (sync) 和流式 (streamed)。这个 SDK 是"代码优先 (code first)"的：工作流逻辑用原生 Python 写，而不是用什么 图领域特定语言 (graph DSLs) 。Codex 的框架在此基础上扩展成了三层架构： Codex Core （智能体代码 + 运行时）、 App Server （双向 JSON RPC API ）、以及 客户端界面 (client surfaces) （CLI、VS Code、网页应用）。所有界面共享同一个框架，这就是为什么"Codex 模型在 Codex 的界面上用起来，比在一个通用聊天窗口里顺手得多"。 LangGraph 把框架建模为一个显式的 状态图 (state graph) 。两个节点（ llm call 和 tool node ）通过一条 条件边 (conditional edge) 连接：如果存在 工具调用 (tool calls) ，就路由到 tool node ；如果没有，就路由到 END。LangGraph 是从 LangChain 的 AgentExecutor 进化来的，后者在 v0.2 被废弃了，因为它难以扩展，而且不支持多智能体。LangChain 的 Deep Agents 明确使用了" 智能体框架 (agent harness) "这个词：内置工具、 规划 (planning) （ write todos 工具）、用于上下文管理的文件系统、 子智能体生成 (subagent spawning) 、以及 持久化记忆 (persistent memory) 。 CrewAI 实现了一种基于角色的 多智能体架构 (multi agent architecture) ： 智能体 (Agent) （围绕 大语言模型 (LLM) 的框架，由角色、目标、背景故事和工具定义）、 任务 (Task) （工作单元）、以及 团队 (Crew) （智能体的集合）。CrewAI 的 Flows 层增加了一个" 在关键之处注入智能的确定性骨架 "，负责路由和验证，而 Crews 则处理自主协作。 AutoGen （正在演进为 Microsoft Agent Framework ）开创了 对话驱动编排 (conversation driven orchestration) 的先河。它的三层架构（Core、AgentChat、Extensions）支持五种 编排模式 (orchestration patterns) ：顺序 (sequential)、并发 (concurrent， 扇出/扇入 (fan out/fan in) )、 群组聊天 (group chat) 、 交接 (handoff) 、以及 magentic （一个管理智能体维护着动态任务台账，协调各路专家）。 SDK 架构对比 脚手架 (scaffolding) 的比喻不是装饰，它非常精确。建筑脚手架是临时基础设施，让工人能够够到原本够不到的地方去施工。它本身不干活，但没有它，工人就上不了高楼。 脚手架隐喻 核心洞见在于：楼盖好了，脚手架就该拆了。模型越强，框架的复杂度就该越低。Manus 在半年内重构了五次，每次重写都在做减法。复杂的工具定义变成了通用的 shell 执行 (shell execution) ，" 管理智能体 (Management agents) "变成了简单的 结构化交接 (structured handoffs) 。 这指向了一个 共同进化原则 (co evolution principle) ：现在的模型在 后训练 (post trained) 时，会把特定的框架纳入训练循环。Claude Code 的模型学会的是它训练时配对的那个特定框架。因为这种紧密耦合，改了工具实现反而可能导致性能下降。 框架设计的" 面向未来的测试 (future proofing test) "是：如果模型更强了，性能自然提升，而框架复杂度不需要增加，那这个设计就是靠谱的。 共同进化原则 每个框架架构师都要面对七个抉择： 七个架构抉择 1. 单智能体 (Single agent) vs. 多智能体 (multi agent) 。 Anthropic 和 OpenAI 都说：先把单智能体榨干再说。多智能体系统有额外开销（路由要多调 LLM、交接时会丢失上下文）。只有当工具重叠超过约 10 个，或者任务域明显分离时，才考虑拆分。 2. ReAct vs. 计划 执行 (plan and execute) 。 ReAct 每一步都把推理和行动搅在一起（灵活，但每步成本高）。 计划 执行 把规划和执行分开。 LLMCompiler 报告称，相比顺序 ReAct 有 3.6 倍 的加速。 3. 上下文窗口 (Context window) 管理策略。 五种生产级方案：基于时间的清理、对话摘要、 观察掩码 (observation masking) 、 结构化笔记 (structured note taking) 、以及 子智能体委托 (sub agent delegation) 。ACON 的研究表明，通过优先保留推理痕迹而非原始工具输出，可以在保持 95%+ 准确率的同时，减少 26% 到 54% 的 token 消耗。 4. 验证循环 (Verification loop) 设计。 计算验证 (Computational verification) （测试、代码检查器）提供确定性的真相。 推理验证 (Inferential verification) （LLM 当裁判）能抓住语义问题，但会增加延迟。Martin Fowler 的 Thoughtworks 团队把这叫 引导器 (guides) （前馈，行动前引导）vs. 传感器 (sensors) （反馈，行动后观察）。 5. 权限与安全架构 (Permission and safety architecture) 。 宽松模式（快但险，大部分操作自动批准）vs. 严格模式（安全但慢，每一步都要 approval）。取决于部署场景。 6. 工具范围策略 (Tool scoping strategy) 。 工具越多，性能往往越差。Vercel 从 v0 里砍掉了 80% 的工具，结果反而更好。Claude Code 通过 懒加载 (lazy loading) 实现了 95% 的上下文缩减。原则：当前这一步需要啥，就暴露啥，绝不多给。 7. 框架厚度 (Harness thickness) 。 多少逻辑应该放在框架里，多少留给模型。Anthropic 赌的是 薄框架 (thin harnesses) + 模型进化。基于图的框架赌的是 显式控制 (explicit control) 。Anthropic 会定期从 Claude Code 的框架里删掉规划步骤，因为新版本的模型已经把这个能力内化了。 两个产品用一模一样的模型，只因为框架设计不同，性能就可能天差地别。 TerminalBench 的证据很明确：只改框架，就能让智能体的排名上下浮动 20 多名 。 智能体框架不是什么已经解决的问题，也不是什么通用 commodity 层。真正的硬工程就在这里：把上下文当稀缺资源来管理、设计能在错误滚雪球之前拦住它的验证循环、构建既保持连续性又不产生幻觉的记忆系统、以及赌一把——到底该搭多少脚手架，又该留给模型多少。 随着模型越来越强，行业正在往 更薄的框架 走。但框架本身不会消失。就算是最强的模型，也需要一个东西来管理它的上下文窗口、执行它的工具调用、持久化它的状态、以及验证它的产出。 下次你的智能体掉链子，别怪模型。看看它的框架。 收工！ 步骤 1（提示词组装） ：Harness 构建完整的输入： 系统提示词 (system prompt) + 工具模式 (tool schemas) + 记忆文件 + 对话历史 + 当前用户消息。重要的上下文会被放置在提示词的开头和结尾（这就是著名的"中间迷失"现象）。 步骤 2（LLM 推理） ：组装好的提示词被送往模型 API。模型生成输出 token：可能是纯文本、工具调用请求，或两者兼有。 步骤 3（输出分类） ：如果模型只生成了文本而没有工具调用，循环结束。如果请求了工具调用，则进入执行阶段。如果请求了交接，则更新当前 Agent 并重启。 步骤 4（工具执行） ：对于每个工具调用，Harness 会验证参数、检查权限、在沙箱环境中执行，并捕获结果。只读操作可以并发执行；写操作则串行处理。 步骤 5（结果打包） ：工具结果被格式化为 LLM 可读的消息。错误会被捕获并作为错误结果返回，让模型能够自我修正。 步骤 6（上下文更新） ：结果被追加到对话历史中。如果接近 上下文窗口 (context window) 上限，Harness 会触发压缩。 步骤 7（循环） ：回到步骤 1。重复直到终止。 终止条件是多层级的：模型产出了没有工具调用的回复、达到最大轮次限制、 token 预算耗尽、护栏绊线被触发、用户主动中断、或返回了安全拒绝。一个简单问题可能只需 1 到 2 轮。一个复杂的重构任务则可能跨越多轮，串联数十个工具调用。 示例工作流 ： 初始化 Agent (Initializer Agent) 先搭建环境（初始化脚本、进度文件、功能列表、首次 git 提交），然后每个后续会话中的 编码 Agent (Coding Agent) 会读取 git 日志和进度文件来定位自己，挑选最高优先级的未完成特性，开始工作，提交代码，并撰写摘要。文件系统跨越上下文窗口，提供了连续性。 Agent 执行周期 Anthropic 的 Claude Agent SDK 通过一个 query() 函数暴露出整个 智能体框架 (harness) ，这个函数创建了智能体循环，并返回一个异步迭代器来流式传输消息。运行时就是一个"傻循环"——所有的智商都在模型里。Claude Code 采用了一个 收集 执行 验证 (Gather Act Verify) 的循环： 收集上下文 (gather context) （搜索文件、读取代码）、 采取行动 (take action) （编辑文件、运行命令）、 验证结果 (verify results) （跑测试、检查输出），然后周而复始。 OpenAI 的 Agents SDK 则通过 Runner 类来实现这个框架，提供三种模式：异步 (async)、同步 (sync) 和流式 (streamed)。这个 SDK 是"代码优先 (code first)"的：工作流逻辑用原生 Python 写，而不是用什么 图领域特定语言 (graph DSLs) 。Codex 的框架在此基础上扩展成了三层架构： Codex Core （智能体代码 + 运行时）、 App Server （双向 JSON RPC API ）、以及 客户端界面 (client surfaces) （CLI、VS Code、网页应用）。所有界面共享同一个框架，这就是为什么"Codex 模型在 Codex 的界面上用起来，比在一个通用聊天窗口里顺手得多"。 LangGraph 把框架建模为一个显式的 状态图 (state graph) 。两个节点（ llm call 和 tool node ）通过一条 条件边 (conditional edge) 连接：如果存在 工具调用 (tool calls) ，就路由到 tool node ；如果没有，就路由到 END。LangGraph 是从 LangChain 的 AgentExecutor 进化来的，后者在 v0.2 被废弃了，因为它难以扩展，而且不支持多智能体。LangChain 的 Deep Agents 明确使用了" 智能体框架 (agent harness) "这个词：内置工具、 规划 (planning) （ write todos 工具）、用于上下文管理的文件系统、 子智能体生成 (subagent spawning) 、以及 持久化记忆 (persistent memory) 。 CrewAI 实现了一种基于角色的 多智能体架构 (multi agent architecture) ： 智能体 (Agent) （围绕 大语言模型 (LLM) 的框架，由角色、目标、背景故事和工具定义）、 任务 (Task) （工作单元）、以及 团队 (Crew) （智能体的集合）。CrewAI 的 Flows 层增加了一个" 在关键之处注入智能的确定性骨架 "，负责路由和验证，而 Crews 则处理自主协作。 AutoGen （正在演进为 Microsoft Agent Framework ）开创了 对话驱动编排 (conversation driven orchestration) 的先河。它的三层架构（Core、AgentChat、Extensions）支持五种 编排模式 (orchestration patterns) ：顺序 (sequential)、并发 (concurrent， 扇出/扇入 (fan out/fan in) )、 群组聊天 (group chat) 、 交接 (handoff) 、以及 magentic （一个管理智能体维护着动态任务台账，协调各路专家）。 SDK 架构对比 脚手架 (scaffolding) 的比喻不是装饰，它非常精确。建筑脚手架是临时基础设施，让工人能够够到原本够不到的地方去施工。它本身不干活，但没有它，工人就上不了高楼。 脚手架隐喻 核心洞见在于：楼盖好了，脚手架就该拆了。模型越强，框架的复杂度就该越低。Manus 在半年内重构了五次，每次重写都在做减法。复杂的工具定义变成了通用的 shell 执行 (shell execution) ，" 管理智能体 (Management agents) "变成了简单的 结构化交接 (structured handoffs) 。 这指向了一个 共同进化原则 (co evolution principle) ：现在的模型在 后训练 (post trained) 时，会把特定的框架纳入训练循环。Claude Code 的模型学会的是它训练时配对的那个特定框架。因为这种紧密耦合，改了工具实现反而可能导致性能下降。 框架设计的" 面向未来的测试 (future proofing test) "是：如果模型更强了，性能自然提升，而框架复杂度不需要增加，那这个设计就是靠谱的。 共同进化原则 每个框架架构师都要面对七个抉择： 七个架构抉择 1. 单智能体 (Single agent) vs. 多智能体 (multi agent) 。 Anthropic 和 OpenAI 都说：先把单智能体榨干再说。多智能体系统有额外开销（路由要多调 LLM、交接时会丢失上下文）。只有当工具重叠超过约 10 个，或者任务域明显分离时，才考虑拆分。 2. ReAct vs. 计划 执行 (plan and execute) 。 ReAct 每一步都把推理和行动搅在一起（灵活，但每步成本高）。 计划 执行 把规划和执行分开。 LLMCompiler 报告称，相比顺序 ReAct 有 3.6 倍 的加速。 3. 上下文窗口 (Context window) 管理策略。 五种生产级方案：基于时间的清理、对话摘要、 观察掩码 (observation masking) 、 结构化笔记 (structured note taking) 、以及 子智能体委托 (sub agent delegation) 。ACON 的研究表明，通过优先保留推理痕迹而非原始工具输出，可以在保持 95%+ 准确率的同时，减少 26% 到 54% 的 token 消耗。 4. 验证循环 (Verification loop) 设计。 计算验证 (Computational verification) （测试、代码检查器）提供确定性的真相。 推理验证 (Inferential verification) （LLM 当裁判）能抓住语义问题，但会增加延迟。Martin Fowler 的 Thoughtworks 团队把这叫 引导器 (guides) （前馈，行动前引导）vs. 传感器 (sensors) （反馈，行动后观察）。 5. 权限与安全架构 (Permission and safety architecture) 。 宽松模式（快但险，大部分操作自动批准）vs. 严格模式（安全但慢，每一步都要 approval）。取决于部署场景。 6. 工具范围策略 (Tool scoping strategy) 。 工具越多，性能往往越差。Vercel 从 v0 里砍掉了 80% 的工具，结果反而更好。Claude Code 通过 懒加载 (lazy loading) 实现了 95% 的上下文缩减。原则：当前这一步需要啥，就暴露啥，绝不多给。 7. 框架厚度 (Harness thickness) 。 多少逻辑应该放在框架里，多少留给模型。Anthropic 赌的是 薄框架 (thin harnesses) + 模型进化。基于图的框架赌的是 显式控制 (explicit control) 。Anthropic 会定期从 Claude Code 的框架里删掉规划步骤，因为新版本的模型已经把这个能力内化了。 两个产品用一模一样的模型，只因为框架设计不同，性能就可能天差地别。 TerminalBench 的证据很明确：只改框架，就能让智能体的排名上下浮动 20 多名 。 智能体框架不是什么已经解决的问题，也不是什么通用 commodity 层。真正的硬工程就在这里：把上下文当稀缺资源来管理、设计能在错误滚雪球之前拦住它的验证循环、构建既保持连续性又不产生幻觉的记忆系统、以及赌一把——到底该搭多少脚手架，又该留给模型多少。 随着模型越来越强，行业正在往 更薄的框架 走。但框架本身不会消失。就算是最强的模型，也需要一个东西来管理它的上下文窗口、执行它的工具调用、持久化它的状态、以及验证它的产出。 下次你的智能体掉链子，别怪模型。看看它的框架。 收工！ 🔗 原文链接： https://mp.weixin.qq.com/s/XnEK8Aoe... https://mp.weixin.qq.com/s/XnEK8Aoe... 原创 DracoVibeCoding DracoVibeCoding Draco正在VibeCoding2026年4月19日 12:17 北京 Agent Harness这个词现在是天天见了，但是Harness的内涵究竟是什么，X上的这篇文章算是很好的科普： 原文： https://x.com/akshay pachaar/status/2041146899319971922 作者： Akshay 🚀 (@akshay pachaar) 这篇文章将深度揭秘 Anthropic、OpenAI、Perplexity 和 LangChain 到底在捣鼓什么。 编排循环 (orchestration loop) 、 工具 (tools) 、 记忆 (memory) 、 上下文管理 (context management) ——凡是你能想到的、能把一个无状态的 大语言模型 (LLM) 变成靠谱 智能体 (agent) 的玩意儿，今天一次性说透。 你可能已经搭了一个聊天机器人。也许还给它接了几个工具，搞了个 ReAct 循环 (ReAct loop) 。演示的时候跑得挺溜。但一旦想做成生产级的玩意儿，车就开始翻了：模型忘了三步之前自己干了啥，工具调用悄无声息地挂了， 上下文窗口 (context window) 里塞满了垃圾信息。 问题不在你的模型，而在模型周围的那堆东西。 LangChain 早就验证过这一点——他们只改了包裹 大语言模型 (LLM) 的底层架构（模型没变，权重没变），结果在 TerminalBench 2.0 上直接从 30 名开外飙到了第 5。另一个研究项目更狠，让 大语言模型 (LLM) 自己去优化这套架构，通过率干到了 76.4%，吊打人工设计的系统。 这套架构现在有了个正式名字： 智能体 harness (agent harness) 。 这个词在 2026 年初才被正式定下来，但概念其实早就存在了。所谓 harness，就是包裹 大语言模型 (LLM) 的一整套软件基础设施： 编排循环 (orchestration loop) 、 工具 (tools) 、 记忆 (memory) 、 上下文管理 (context management) 、 状态持久化 (state persistence) 、 错误处理 (error handling) 和 安全护栏 (guardrails) 。Anthropic 的 Claude Code 文档说得干脆：SDK 就是"驱动 Claude Code 的 智能体 harness (agent harness) "。OpenAI 的 Codex 团队也是同一个路数，直接把 "agent" 和 "harness" 划等号，指的都是让 大语言模型 (LLM) 真正能派上用场的那套非模型基础设施。 我特别喜欢 LangChain 的 Vivek Trivedy 说的那句经典论断： 如果你不是模型，你就是 harness。 这里有个很容易把人绕晕的区别。" 智能体 (Agent) " 是一种 涌现行为 (emergent behavior) ：有明确目标、会用工具、能自我纠正，是用户实际交互的那个存在。而 harness 是产生这种行为的机器。所以当有人说"我搭了一个 agent"，他的潜台词其实是：我搭了一套 harness，然后把它指向了一个模型。 Agent 与 Harness 的 CPU 和 OS 类比 Beren Millidge 在 2023 年的文章《Scaffolding for AI》里，把这个类比说得极其精准： 一个裸的 大语言模型 (LLM) ，就像一台没有内存、没有硬盘、没有 I/O 的 CPU。 上下文窗口 (context window) 充当内存（快但容量有限），外部数据库充当硬盘存储（大但慢），工具集成充当设备驱动。而 harness 就是操作系统。正如 Millidge 所写："我们重新发明了 冯·诺依曼架构 (Von Neumann architecture) "，因为这是任何计算系统都绕不开的自然抽象。 围绕模型，有三层同心圆式的工程体系： • 提示工程 (Prompt engineering) ：精心打磨模型收到的指令。 • 上下文工程 (Context engineering) ：管理模型在什么时候看到什么内容。 • Harness 工程 (Harness engineering) ：涵盖以上两者，再加上整个应用基础设施—— 工具编排 (tool orchestration) 、 状态持久化 (state persistence) 、 错误恢复 (error recovery) 、 验证循环 (verification loops) 、 安全强制执行 (safety enforcement) 和 生命周期管理 (lifecycle management) 。 Harness 不是给 提示 (prompt) 套个壳子。它是让 自主智能体 (autonomous agent) 行为成为可能的完整系统。 综合 Anthropic、OpenAI、LangChain 以及更广泛实践社区的经验，一个生产级的 智能体 harness (agent harness) 包含十二个独立组件。咱们一个一个来盘。 1. 编排循环 (Orchestration Loop) —— Agent 的心跳 这就是 agent 的"心跳"。它实现了 思考 行动 观察循环 (Thought Action Observation, TAO) ，也就是我们常说的 ReAct 循环 。整个流程跑起来就像这样：组装提示词 → 呼叫大模型 → 解析输出 → 执行工具调用 → 把结果喂回去 → 重复，直到搞定收工。 从机械结构上看，它往往就是个 while 循环。真正的复杂度全藏在循环管理的那些"杂事"里，而不是循环本身。Anthropic 把他们的运行时比作一个" 笨循环 (dumb loop) "——所有智商都长在模型身上，执行框架 (harness) 只管轮流转场。 2. 工具 (Tools) —— Agent 的手 工具是 agent 的"手"。它们以 schema （名称、描述、参数类型）的形式定义好，再注入到大语言模型 (LLM) 的上下文里，让模型知道自己手里有什么牌。工具层 (tool layer) 负责注册、schema 校验、参数提取、 沙箱执行 (sandboxed execution) 、结果捕获，以及把结果格式化成模型能读懂的 观察结果 (observations) 。 Claude Code 提供了六大类工具：文件操作、搜索、执行、网页访问、代码智能和 子智能体孵化 (subagent spawning) 。OpenAI 的 Agents SDK 支持函数工具（通过 function calling ）、托管工具（WebSearch、CodeInterpreter、FileSearch）以及 MCP 服务器工具 (MCP server tools) 。 3. 记忆 (Memory) —— 多个时间尺度的存档 记忆在多个时间尺度上同时运作。 短期记忆 (Short term memory) 就是单次会话里的对话历史。 长期记忆 (Long term memory) 则跨会话持久化：Anthropic 用 claude.md 项目文件和自动生成的