【翻译】Agent Harness 解剖结构

用户60007181910
0 阅读13分钟

Agent Harness 解剖结构

image.png

深入 Anthropic、OpenAI、Perplexity 与 LangChain 实际在构建什么：编排循环、工具、记忆、上下文管理，以及把无状态大语言模型变成可用智能体所需的一切。

你做过聊天机器人。也许还接过一个带几个工具的 ReAct 循环。Demo 能跑。一旦要做生产级系统，轮子就掉了：模型忘了三步前做了什么，工具调用静默失败，上下文窗口塞满垃圾。

问题不在模型，而在模型周围的一切。

LangChain 证明了这一点：他们只改了包裹大语言模型的基础设施（同一模型、同一权重），在 TerminalBench 2.0 上从 30 名开外跳到第 5。另一项研究让大语言模型优化基础设施本身，达到 76.4% 通过率，超过人工设计的系统。

这套基础设施现在有了名字：agent harness（智能体 Harness）。

什么是 Agent Harness？

这一术语在 2026 年初被正式化，但概念早就存在。Harness 是包裹大语言模型的完整软件基础设施：编排循环、工具、记忆、上下文管理、状态持久化、错误处理与护栏。Anthropic 的 Claude Code 文档说得很直白：SDK 就是「驱动 Claude Code 的 agent harness」。OpenAI 的 Codex 团队用同一套 framing，明确把「agent」与「Harness」等同起来，指让大语言模型真正好用的非模型基础设施。

我很喜欢 LangChain Vivek Trivedy 的经典公式：「如果你不是模型，你就是 Harness。」

容易让人混淆的是这层区分。「智能体」是涌现出来的行为：面向目标、会用工具、能自我纠错的实体，用户与之交互。Harness 是产生这套行为的机器。有人说「我做了个 agent」，意思是做了 Harness 并指向某个模型。

image.png

Beren Millidge 在 2023 年文章 《Scaffolded LLMs as Natural Language Computers》 里把这个类比说精确了。裸LLM像没有 RAM、没有磁盘、没有 I/O 的 CPU。Context Window充当 RAM（快但有限）。外部数据库像磁盘（大但慢）。工具集成充当设备驱动。Harness 就是操作系统。 Millidge 写道：「我们重新发明了冯·诺依曼架构」——因为对任何计算系统这都是自然抽象。

三层工程

模型周围有三层同心工程：

  • 提示词工程（prompt engineering）：编写模型收到的指令。

  • 上下文工程（context engineering）：管理模型何时看到什么。

  • Harness 工程（Harness engineering）：涵盖前两者，再加上完整应用基础设施：工具编排、状态持久化、错误恢复、验证循环、安全强制与生命周期管理。

Harness 不是包在提示词外的一层壳，而是让自主智能体行为成为可能的完整系统。

生产级 Harness 的 12 个组件

综合 Anthropic、OpenAI、LangChain 与更广泛的实践社区，生产级 agent harness 有十二个独立组件。逐一过一遍。

image.png

1. 编排循环（Orchestration Loop）

这是心跳。它实现 Thought-Action-Observation（TAO）周期，也叫 ReAct 循环。循环流程：组装提示词 → 调用大语言模型 → 解析输出 → 执行工具调用 → 把结果喂回 → 重复直到结束。

机制上往往就是一个 while 循环。复杂度在于循环所管理的一切，不在循环本身。Anthropic 把运行时描述为「dumb loop」：所有智能在模型里，Harness 只管轮次。

2. 工具（Tools）

工具是智能体的手。它们以 schema（名称、描述、参数类型）定义，注入大语言模型上下文，让模型知道有什么可用。工具层负责注册、schema 校验、参数提取、沙箱执行、结果捕获，以及把结果格式化成模型可读的 observation。

Claude Code 在六类里提供工具：文件操作、搜索、执行、Web 访问、代码智能与子智能体生成。OpenAI Agents SDK 支持 function tools（通过 @function_tool）、托管工具（WebSearch、CodeInterpreter、FileSearch）与 MCP 服务器工具。

3. 记忆（Memory）

记忆在多个时间尺度上运作。短期记忆是会话内的对话历史。长期记忆跨会话持久化：Anthropic 用 CLAUDE.md 项目文件与自动生成的 MEMORY.md 文件；LangGraph 用命名空间组织的 JSON Store；OpenAI 支持由 SQLite 或 Redis 支撑的 Sessions。

Claude Code 实现三层层次：轻量索引（每条约 150 字符，始终加载）、按需拉入的详细主题文件、以及仅通过搜索访问的原始 transcript。关键设计原则：智能体把自身记忆当作「提示」，行动前先对照真实状态验证。

4. 上下文管理（Context Management）

许多智能体在这里静默失败。核心问题是 context rot（上下文腐化）：关键内容落在窗口中间位置时，模型性能下降 30% 以上（Chroma 研究，与 Stanford「Lost in the Middle」结论一致）。即使百万 token 窗口，随上下文增长，指令遵循也会退化。

生产策略包括：

  • Compaction（压缩）：接近上限时摘要对话历史（Claude Code 保留架构决策与未解 bug，丢弃冗余工具输出）

  • Observation masking（观测掩蔽）：JetBrains Junie 隐藏旧工具输出，保留工具调用可见

  • Just-in-time retrieval（即时检索）：维护轻量标识符并动态加载数据（Claude Code 用 grep、glob、head、tail，而非整文件加载）

  • Sub-agent delegation（子智能体委派）：每个子智能体深度探索，但只返回 1,000–2,000 token 的 condensed 摘要

Anthropic 的 context engineering 指南说目标是：找到尽可能小的高信号 token 集合，最大化期望结果的概率。

5. 提示词构建（Prompt Construction）

这组装模型每一步实际看到的内容。层次结构：系统提示词、工具定义、记忆文件、对话历史与当前用户消息。

OpenAI Codex 用严格优先级栈：服务端控制的 system message（最高）、工具定义、开发者指令、用户指令（级联 AGENTS.md 文件，32 KiB 上限），然后是对话历史。

6. 输出解析（Output Parsing）

现代 Harness 依赖原生 tool calling：模型返回结构化 tool_calls 对象，而非需解析的自由文本。Harness 检查：有工具调用？执行并循环。没有？那就是最终答案。

结构化输出方面，OpenAI 与 LangChain 都支持通过 Pydantic 模型做 schema 约束响应。遗留方案如 RetryWithErrorOutputParser（把原始提示词、失败 completion 与解析错误一起喂回模型）在边缘场景仍可用。

7. 状态管理（State Management）

LangGraph 把状态建模为流经图节点的 typed dictionary，reducer 合并更新。Checkpoint 在 super-step 边界发生，支持中断后恢复与时间旅行调试。OpenAI 提供四种互斥策略：应用内存、SDK sessions、服务端 Conversations API，或轻量 previous_response_id 链式。Claude Code 另辟蹊径：用 git commit 作 checkpoint，progress 文件作结构化 scratchpad。

8. 错误处理（Error Handling）

这很重要：十步流程每步 99% 成功率，端到端也只有约 90.4%。错误会迅速积累。

LangGraph 区分四类错误：transient（退避重试）、LLM-recoverable（以 ToolMessage 返回错误让模型调整）、user-fixable（中断等人输入）、unexpected（冒泡供调试）。Anthropic 在 tool handler 内捕获失败并以 error result 返回，保持循环运行。Stripe 生产 Harness 把重试上限设为 2。

9. 护栏与安全（Guardrails and Safety）

OpenAI SDK 三层：input guardrails（首个 agent 上跑）、output guardrails（最终输出上跑）、tool guardrails（每次工具调用跑）。「tripwire」机制触发后立即 halt agent。

Anthropic 在架构上把权限执行与模型推理分开。模型决定尝试什么；工具系统决定允许什么。Claude Code 独立 gate 约 40 种离散工具能力，三阶段：项目加载时建立信任、每次工具调用前权限检查、高风险操作需用户明确确认。

10. 验证循环（Verification Loops）

这是玩具 demo 与生产智能体的分水岭。Anthropic 推荐三种：基于规则的反馈（测试、linter、类型检查）、视觉反馈（UI 任务用 Playwright 截图）、LLM-as-judge（独立子智能体评估输出）。

Claude Code 创造者 Boris Cherny 指出：给模型验证自身工作的方式，质量可提升 2–3 倍。

11. 子智能体编排（Subagent Orchestration）

Claude Code 三种执行模型：Fork（与父上下文字节级相同拷贝）、Teammate（独立终端 pane，基于文件的 mailbox 通信）、Worktree（独立 git worktree，每 agent 隔离分支）。OpenAI SDK 支持 agents-as-tools（专家处理有界子任务）与 handoffs（专家完全接管）。LangGraph 把子智能体实现为嵌套状态图。

循环运转：逐步走查

了解组件后，看它们如何在一个周期里协同。

image.png

Step 1（Prompt Assembly）：Harness 构造完整输入：system prompt + 工具 schema + 记忆文件 + 对话历史 + 当前用户消息。重要上下文放在提示词开头与结尾（「Lost in the Middle」结论）。

Step 2（LLM Inference）：组装好的提示词进入模型 API。模型生成输出 token：文本、工具调用请求，或两者兼有。

Step 3（Output Classification）：若模型只产出文本、无工具调用，循环结束。若请求工具调用，进入执行。若请求 handoff，更新当前 agent 并重启。

Step 4（Tool Execution）：对每个工具调用，Harness 校验参数、检查权限、在沙箱执行并捕获结果。只读操作可并发；变更操作串行。

Step 5（Result Packaging）：工具结果格式化为模型可读 message。错误被捕获并以 error result 返回，供模型自纠。

Step 6（Context Update）：结果追加到对话历史。若接近上下文窗口上限，Harness 触发 compaction。

Step 7（Loop）：回到 Step 1，重复直到终止。

终止条件分层：模型产出无工具调用的响应、超过最大轮次、token 预算耗尽、guardrail tripwire 触发、用户中断，或安全拒绝。简单问题可能 1–2 轮；复杂重构可能跨多轮链式数十次工具调用。

对于跨多个上下文窗口的长时任务，Anthropic 发展了两阶段「Ralph Loop」模式：Initializer Agent 搭建环境（init 脚本、progress 文件、feature 列表、初始 git commit），之后每个会话的 Coding Agent 读 git log 与 progress 文件以定位自身，选最高优先级未完成 feature，实现、commit 并写摘要。

文件系统提供跨上下文窗口的连续性。

真实框架如何实现这一模式

image.png

Anthropic Claude Agent SDK 通过单个 query() 函数暴露 Harness，创建 agentic loop 并返回流式 message 的 async iterator。运行时是「dumb loop」，智能全在模型。Claude Code 用 Gather-Act-Verify 周期：收集上下文（搜文件、读代码）→ 行动（改文件、跑命令）→ 验证结果（跑测试、查输出）→ 重复。

OpenAI Agents SDK 通过 Runner 类实现 Harness，三种模式：async、sync、streamed。SDK 是「code-first」：工作流逻辑用原生 Python 表达，而非图 DSL。

Codex Harness 扩展为三层：Codex Core（agent 代码 + runtime）、App Server（双向 JSON-RPC API）、客户端面（CLI、VS Code、Web app）。所有面共享同一 Harness，所以「Codex 模型在 Codex 面上比通用聊天窗口更好用」。

LangGraph 把 Harness 建模为显式状态图。两个节点（llm_call 与 tool_node）由条件边连接：有 tool calls 则路由到 tool_node，否则到 END。LangGraph 从 LangChain 的 AgentExecutor 演化而来；AgentExecutor 在 v0.2 弃用，因难扩展且缺多智能体支持。LangChain 的 Deep Agents 明确使用「agent harness」一词：内置工具、规划（write_todos 工具）、用于上下文管理的文件系统、子智能体生成与持久记忆。

CrewAI 实现基于角色的多智能体架构：Agent（围绕大语言模型的 Harness，由 role、goal、backstory 与 tools 定义）、Task（工作单元）、Crew（agent 集合）。CrewAI Flows 层加入「确定性骨干 + 该智能处才上智能」，管路由与校验，Crew 负责自主协作。

AutoGen（演进为 Microsoft Agent Framework）开创对话驱动编排。三层架构（Core、AgentChat、Extensions）支持五种编排模式：sequential、concurrent（fan-out/fan-in）、group chat、handoff、magentic（manager agent 维护动态 task ledger 协调专家）。

脚手架隐喻

用脚手架作比喻并非花哨，而是十分贴切。建筑脚手架是一种临时性基础设施，它使工人能够建造原本无法到达的结构。脚手架本身并不进行建造，但如果没有它，工人就无法到达楼上。

image.png

关键洞见：楼建完脚手架就拆。 模型变强，Harness 复杂度应下降。Manus 六个月里重写五次，每次删复杂度：复杂工具定义变成通用 shell 执行，「管理 agent」变成简单结构化 handoff。

这指向协同演化原则：模型现在在特定 Harness 在环的情况下做 post-training。Claude Code 的模型学会了它训练时那套 Harness。改工具实现可能降性能，因为耦合很紧。

Harness 设计的「未来证明测试」：更强模型下性能提升且不必加 Harness 复杂度，设计就站得住。

image.png

定义每个 Harness 的七个决策

每个 Harness 架构师都面对七个选择：

示意图

  1. 单智能体 vs. 多智能体。 Anthropic 与 OpenAI 都说：先把单 agent 最大化。多智能体系统增加开销（路由额外大语言模型调用、handoff 丢上下文）。仅在工具过载超过约 10 个重叠工具，或任务域清晰分离时再拆。

  2. ReAct vs. plan-and-execute。 ReAct 每步交错推理与行动（灵活但单步成本更高）。Plan-and-execute 把规划与执行分开。LLMCompiler 报告相对顺序 ReAct 有 3.6 倍加速。

  3. 上下文窗口管理策略。 五种生产做法：按时间清理、对话摘要、observation masking、结构化笔记、子智能体委派。ACON 研究显示，优先保留推理 trace 而非原始工具 输出，可 减少 26–54% token 且保持 95%+ 准确率。

  4. 验证循环设计。 计算验证（测试、linter）提供确定性 ground truth。推理验证（LLM-as-judge）抓语义问题但增延迟。Martin Fowler 的 Thoughtworks 团队 framing 为 guides（feedforward，行动前 steer）对 sensors（feedback，行动后 observe）。

  5. 权限与安全架构。 宽松（快但险，多数操作自动批准）对 restrictive（慢但安全，每步需批准）。取决于部署语境。

  6. 工具范围策略。 工具越多往往性能越差。Vercel 从 v0 去掉 80% 工具 结果更好。Claude Code 通过 lazy loading 实现 95% 上下文缩减。原则：只暴露当前步骤所需的最小工具集。

  7. Harness 厚度。 多少逻辑在 Harness、多少留给模型。Anthropic 押注薄 Harness + 模型改进；基于图的框架押注显式控制。Anthropic 常在新模型内化能力后，从 Claude Code Harness 删掉规划步骤。

Harness 即产品

两个产品用同一模型，仅因 Harness 设计不同，表现可以天差地别。TerminalBench 证据清楚：只改 Harness 就能让 agent 排名变动 20+ 位。

Harness 不是已解问题或 commodity 层。难工程在这里：把上下文当稀缺资源管理、设计在失败复合前抓住问题的验证循环、建 continuity 但不 hallucinate 的记忆系统，以及押注该搭多少脚手架、该留给模型多少。

领域正随模型改进走向更薄 Harness。但 Harness 本身不会消失。

再强的模型也需要某种机制来管理上下文窗口、执行工具调用、持久状态并验证工作。

下次 agent 失败，别怪模型。看 Harness。

就这些！

若读得开心：

关注我 → @akshay_pachaar ✔️

我每天都会分享 AI、机器学习与 vibe coding 最佳实践的教程与洞见。

avatar
文章
阅读
粉丝