深度拆解：AI Agent Harness 的构造

深度拆解：AI Agent Harness 的构造

• ID: 08dc63f3
• 原文链接: https://baoyu.io/translations/2026-05-10/akshay-pachaar-2041146899319971922
• 作者: Akshay（翻译：宝玉）
• 日期: 2026-05-10
• 分类: agents
• 标签: agents, harness, claude-code, codex, langchain, anthropic, openai
• 质量评分: 4/5
• 抓取时间: 2026-06-27T12:35:00

中文翻译

本文深入探讨 Anthropic、OpenAI、Perplexity 和 LangChain 究竟在开发什么——编排循环、工具、记忆、上下文管理，以及将"无状态"的大语言模型转变为全能 Agent 的底层机制。

为什么 Harness 这么重要

你可能已经开发过聊天机器人，甚至用一些工具搭建了一个 ReAct 循环。跑 Demo 时看着挺好，但一旦投入生产环境，系统就开始掉链子：模型忘记三步前做了什么，工具调用悄悄报错，上下文窗口里塞满毫无意义的垃圾信息。

问题不在模型本身，而在模型外围的基础设施。LangChain 证明了这一点：他们仅仅通过改变包裹大语言模型的底层架构——模型没变、参数没变——就让系统在 TerminalBench 2.0（衡量 AI Agent 处理命令行任务能力的权威基准）上的排名从 30 名开外飙升到第 5 名。另一项研究通过让 LLM 自己去优化这套架构，实现了 76.4% 的通过率，甚至超过人类精心设计的系统。

这套基础设施如今有了一个正式的名字：AI Agent Harness。

什么是 Agent Harness

Harness 是包裹在大语言模型之外的完整软件架构：编排循环、工具、记忆、上下文管理、状态持久化、错误处理和护栏（Guardrails）。Anthropic 在 Claude Code 文档中明确指出 SDK 就是"驱动 Claude Code 的 Agent Harness"。OpenAI 的 Codex 团队也使用同样说法，将"Agent"与"Harness"等同。

LangChain 的 Vivek Trivedy 给出的定义公式很精准："如果你不是模型本身，那你就是 Harness。"

"AI Agent" 是用户感知到的行为体现（有目标、会用工具、能自我纠错的实体）；"Harness" 是产生这种行为的背后机器。当有人说"我开发了一个 Agent"时，他真正的意思是"我开发了一套 Harness 并接入了模型"。

Beren Millidge 在 2023 年的博文中做了精准的类比：原生 LLM 像一个没有内存、没有硬盘、没有输入输出设备的 CPU。上下文窗口是内存（快但容量有限），外部数据库是硬盘（大但速度慢），工具集成是设备驱动程序，Harness 就是操作系统。

工程化的三个层次

• 提示词工程 (Prompt engineering)：精心设计模型接收到的指令。
• 上下文工程 (Context engineering)：管理模型在什么时间点能看到什么内容。
• Harness 工程 (Harness engineering)：涵盖前两者，再加上整个应用架构——工具编排、状态持久化、错误恢复、验证循环、安全执行、生命周期管理。

Harness 不是包裹提示词的套壳，而是让 Agent 能够自主行动的完整系统。

生产级 Harness 的 12 个核心组件

1. 编排循环 (The Orchestration Loop)

系统的"心脏"，实现"思考-行动-观察"（TAO / ReAct）循环。技术上看通常只是 while 循环，复杂之处在于循环要处理的各种状态和逻辑。Anthropic 描述其运行时为"笨循环"，智慧全在模型里，Harness 只负责回合切换。

2. 工具 (Tools)

Agent 的"双手"。被定义为结构化模式（名称、描述、参数类型），注入到模型上下文。工具层负责注册、格式校验、参数提取、沙箱执行、结果捕获，并最终格式化为模型可读的"观察结果"。

Claude Code 提供六大类工具：文件操作、搜索、执行、网页访问、代码分析、子 Agent 创建。OpenAI Agents SDK 支持函数工具（@function_tool）、托管工具（网页搜索、代码解释器、文件搜索）以及 MCP 服务器工具。

3. 记忆 (Memory)

• 短期记忆：单次会话中的对话历史
• 长期记忆：跨多个会话持久存在

Anthropic 使用项目文件和自动生成的 memory.md 文件；LangGraph 用按命名空间组织的 JSON 存储；OpenAI 支持 SQLite 或 Redis 驱动的会话存储。

Claude Code 实现三层记忆架构：轻量级索引（每条约 150 字符，始终加载）、按需调用的详细主题文件、仅通过搜索访问的原始对话记录。核心原则：Agent 将自己的记忆视为"提示"，行动前必须根据实际状态验证。

4. 上下文管理 (Context Management)

核心问题是上下文腐烂——关键信息处于窗口中间位置时，模型表现下降 30% 以上（斯坦福"迷失在中间"现象）。即便百万级 Token 窗口，随上下文增长指令遵循能力也会退化。

生产环境应对策略：

• 压缩 (Compaction)：接近限制时总结对话历史（保留架构决策与未修复 Bug，丢弃冗余工具输出）
• 观察掩码 (Observation masking)：隐藏旧工具输出但保留调用记录
• 即时检索 (Just-in-time retrieval)：仅保留轻量级标识符，动态加载数据
• 子 Agent 委托：每个子 Agent 深度探索，仅返回 1000–2000 Token 的浓缩摘要

Anthropic 上下文工程指南的目标：找到能最大化达成目标概率的、信号最强的最小 Token 集合。

5. 提示词构建 (Prompt Construction)

层级化：系统提示词、工具定义、记忆文件、对话历史、当前用户消息。OpenAI Codex 使用严格的优先级栈：服务器控制的系统消息（最高）→ 工具定义 → 开发者指令 → 用户指令 → 对话历史。

6. 输出解析 (Output Parsing)

现代 Harness 依赖原生工具调用，模型返回结构化 tool_calls 对象。Harness 检查：是否有工具调用？有则执行并继续循环；没有则当前输出即为最终答案。

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 三个层级：输入护栏（在第一个 Agent 运行时检查）、输出护栏（检查最终结果）、工具护栏（每次调用工具前检查）。一旦触发"绊网"机制，Agent 立即停止。

Anthropic 在架构上将"权限执行"与"模型推理"分离：模型决定想做什么，但 Harness 决定允许做什么。

10. 验证循环 (Verification Loops)

区分"玩具演示"和"生产级 Agent"的关键。Anthropic 推荐三种方法：基于规则的反馈（测试、代码检查）、视觉反馈（通过 Playwright 截取 UI 截图）、以 LLM 为裁判（LLM-as-judge，由另一个子 Agent 评估输出）。

Claude Code 的创造者 Boris Cherny 指出：让模型能验证自己的工作，产出质量能提升 2–3 倍。

11. 子 Agent 编排 (Subagent Orchestration)

Claude Code 支持三种模式：克隆（Fork，复制父级上下文）、队友（Teammate，通过文件邮箱通信的独立窗口）、工作树（Worktree，独立 Git 分支）。OpenAI 支持将 Agent 作为工具（专家处理子任务）或移交（专家接管控制权）。

一次循环如何跑

1. 提示词组装：Harness 构建完整输入 2. 模型推理：组装内容发给模型 API，生成 Token（文本或工具调用请求） 3. 输出分类：无工具调用则循环结束；有则进入执行 4. 工具执行：Harness 校验参数、检查权限，沙箱运行并捕获结果 5. 结果打包：格式化为模型可读消息，捕获错误便于模型自愈 6. 上下文更新：结果追加到历史，必要时触发压缩 7. 循环：返回第一步直到满足退出条件

主流框架实现对比

• Anthropic (Claude Agent SDK)：query() 函数暴露 Harness，运行时是"笨循环"，智慧全在模型里
• OpenAI (Agents SDK)："代码优先"策略，工作流逻辑用 Python 表达而非复杂图形语言
• LangGraph：Harness 建模为显式状态图，强调精细控制
• CrewAI：基于角色的多 Agent 协作，"流程层"管理确定性骨干逻辑
• AutoGen（微软）：支持顺序、群聊、移交、动态任务管理多种编排模式

Harness 的 7 个关键设计决策

1. 单 Agent vs. 多 Agent：先充分挖掘单 Agent 潜力；多 Agent 带来额外开销与信息损耗 2. ReAct vs. 先规划后执行：ReAct 灵活但成本高，先规划后执行速度更快 3. 上下文管理策略：总结对话还是动态加载？ 4. 验证循环设计：硬性代码测试还是 LLM 评分？ 5. 权限与安全架构：自动批准还是步步确认？ 6. 工具范围管理：暴露当前步骤所需的最小工具集效果最佳 7. Harness 厚度：多少逻辑写死在系统里、多少留给模型发挥？

Harness 即产品

两个使用完全相同模型的 Agent，性能可能天差地别，原因就在于 Harness 设计。TerminalBench 的证据已经明确：仅改变 Harness，就能让排名变动 20 多位。

Harness 不是已经解决的问题，也不是通用商品层。它是硬核工程能力的体现：如何将上下文视为稀缺资源管理？如何设计验证循环防止错误累积？如何构建不产生幻觉的记忆系统？

随着模型越来越强，Harness 会变薄，但它永远不会消失。即使最强大的模型，也需要系统来管理窗口、执行代码、保存状态并验证工作。

*来源：宝玉的分享 2026-05-10，原文作者 Akshay（X: @akshay_pachaar）*

English Original

This piece dives deep into what Anthropic, OpenAI, Perplexity, and LangChain are actually building—the orchestration loops, tools, memory, context management, and underlying mechanisms that turn "stateless" LLMs into all-powerful Agents.

Why Harness matters

You may have built chatbots or even a ReAct loop. Demos look great, but in production: models forget what they did three steps ago, tool calls fail silently, context windows fill with meaningless junk.

The problem isn't the model—it's the infrastructure around it. LangChain proved this: by only changing the underlying architecture wrapping the LLM—same model, same parameters—they jumped from outside top-30 to #5 on TerminalBench 2.0. Another study had LLMs self-optimize this architecture to achieve 76.4% pass rate, exceeding human-designed systems.

This infrastructure now has a formal name: AI Agent Harness.

What is Agent Harness

Harness is the complete software architecture wrapping the LLM: orchestration loops, tools, memory, context management, state persistence, error handling, guardrails. Anthropic's Claude Code documentation explicitly calls the SDK the "Agent Harness driving Claude Code." OpenAI's Codex team uses the same framing.

LangChain's Vivek Trivedy nails it: "If you're not the model itself, you're the Harness."

"AI Agent" is the user-perceived behavior (goal-driven, tool-using, self-correcting entity); "Harness" is the machine producing that behavior.

Beren Millidge's 2023 analogy: raw LLMs are like a CPU with no RAM, no disk, no I/O. Context window is memory (fast but limited), external DB is disk (large but slow), tool integration is device drivers, Harness is the OS.

Three layers of engineering

• Prompt engineering: carefully craft model instructions
• Context engineering: manage what the model sees at each point
• Harness engineering: both plus the full application architecture—tool orchestration, state persistence, error recovery, verification loops, safe execution, lifecycle management

Harness isn't a wrapper around prompts; it's the complete system enabling autonomous agent action.

12 core components of production-grade Harness

1. Orchestration Loop — the "heart"; implements Think-Act-Observe (TAO/ReAct) loop 2. Tools — agent's "hands"; structured schemas registered with the model 3. Memory — short-term (single conversation history) + long-term (cross-session) 4. Context Management — handle "context rot" (30%+ performance drop when key info is mid-window) 5. Prompt Construction — layered: system prompt, tool defs, memory files, dialog history, current message 6. Output Parsing — modern Harnesses rely on native tool calling (structured tool_calls) 7. State Management — typed dicts flowing through graph nodes; checkpointing for resume + time-travel debugging 8. Error Handling — errors snowball: 99% per step × 10 steps = 90.4% end-to-end 9. Guardrails and Safety — input/output/tool-level checks; tripwires stop the agent 10. Verification Loops — distinguishes toy demos from production agents; +2-3x output quality 11. Subagent Orchestration — Fork/Teammate/Worktree (Claude Code); Agent-as-tool/Handoff (OpenAI) 12. (implicit) Lifecycle management, safe execution

How a loop runs

1. Prompt assembly 2. Model inference (text or tool call request) 3. Output classification (tool call? loop continues : end) 4. Tool execution (validate, check permissions, sandbox run, capture) 5. Result packaging (model-readable message, capture errors for self-healing) 6. Context update (append to history, trigger compaction if needed) 7. Loop back to step 1

Mainstream framework implementations

• Anthropic (Claude Agent SDK): exposes Harness via query(); runtime is "dumb loop," wisdom in model
• OpenAI (Agents SDK): code-first strategy; workflow logic in Python, not complex graph languages
• LangGraph: explicit state graphs; emphasis on fine-grained flow control
• CrewAI: role-based multi-agent collaboration; "process layer" manages deterministic backbone
• AutoGen (Microsoft): multiple orchestration modes—sequential, group chat, handoff, dynamic task management

7 key design decisions for Harness

1. Single Agent vs. Multi-Agent: exhaust single-agent potential first 2. ReAct vs. Plan-then-Execute: ReAct flexible but costly; plan-then-execute faster 3. Context management strategy: summarization vs. dynamic loading 4. Verification loop design: hard tests vs. LLM-as-judge 5. Permissions and safety architecture: auto-approve vs. step-confirm 6. Tool scope management: expose minimum necessary tools per step 7. Harness thickness: how much logic is hardcoded vs. left to the model

Harness IS the product

Two agents using identical models can have wildly different performance, all due to Harness design. TerminalBench evidence is clear: only changing Harness moves rankings by 20+ places.

Harness is not a solved problem nor a generic commodity layer. It's hardcore engineering: managing context as a scarce resource, designing verification loops to prevent error accumulation, building memory systems that don't hallucinate.

As models get stronger, Harness thins—but never disappears. Even the most powerful models need systems to manage windows, execute code, persist state, and verify work.

*Source: baoyu.io translation 2026-05-10, original by Akshay (@akshay_pachaar)*