What is an Agent Harness?
Summary
Agent Harness 是将 AI 模型转变为可用 Agent 的所有代码、配置和执行逻辑的统称。模型提供智能，Harness 提供状态管理、工具执行、记忆、编排和可执行约束。模型是常量，Harness 是变量——同样的模型在不同 Harness 下性能排名可以从 top 5 跌到 top 30 以外。
Core Definition
Agent = Model + Harness — Vivek Trivedy, LangChain
原始模型是无状态文本预测器：接收文本，生成文本，然后遗忘一切。Harness 让它成为 Agent。
即使是最基础的聊天机器人也证明了这一点——当你用循环包装模型来跟踪历史消息并追加新用户输入时，你就构建了一个原始 Harness。
Harness 包含什么
| 组件 | 说明 |
|---|---|
| System Prompts | 在任何用户消息到达前塑造行为的常驻指令 |
| Tools & MCPs | 模型用于行动的模式、描述和执行逻辑 |
| Bundled Infrastructure | 文件系统、浏览器、bash、沙箱 |
| Orchestration Logic | 子 Agent 生成、模型路由、Agent 间交接 |
| Hooks & Middleware | 压缩触发器、确认门、确定性执行强制 |
Framework vs Runtime vs Harness
| 层级 | 示例 | 角色 |
|---|---|---|
| Framework | LangChain, CrewAI, AutoGPT | 提供构建 Agent 的抽象 |
| Runtime | LangGraph | 管理执行状态和持久化任务流 |
| Harness | Claude Code, Codex, Cursor, Builder.io | 结合两者并添加领域特定配置、约束和基础设施 |
Node.js 类比：
- Node = Runtime
- Express = Framework
- Next.js = Harness
What a Harness Actually Does
Harness 提供原始模型缺乏的六种基础能力：
1. 持久存储（文件系统 & Git）
模型只能在上下文窗口内操作。文件系统解决了这个问题：
- Agent 获得工作空间来读取数据、代码和文档
- 工作可以增量添加和卸载，而非全部保存在上下文中
- 中间输出在会话间持久化
Git 将文件系统扩展为协调表面：
- 多 Agent 和人类通过共享文件协调
- 一个 Agent 向另一个 Agent 交接时，通过文件系统而非共享上下文窗口
2. Bash & 代码执行
预配置工具覆盖 Harness 设计者预期的情况，Bash 覆盖其他一切。
当模型可以编写和执行代码时，它能动态设计自己的工具，而非受限于固定工具集。这就是 Agentic 工作流在 Harness 层面的样子。
3. 沙箱安全执行
Agent 生成的代码在本地运行是安全风险。单一本地环境无法扩展到并行 Agent 工作负载。
沙箱解决两个问题：
- 隔离执行环境
- 允许列表命令
- 预安装工具
- 浏览器访问用于输出验证
- 测试运行器用于自我检查
4. 记忆与搜索连续性
记忆文件（如 AGENTS.md）在 Agent 启动时注入上下文。当 Agent 更新此文件，Harness 加载更新版本。这是超越任何单一上下文窗口的持久记忆。
网络搜索和 MCP 工具（如 Context7）解决知识截止日期问题。Harness 处理检索，模型请求信息。
5. 上下文管理对抗上下文腐烂
上下文腐烂（Context Rot）：模型性能随上下文窗口填满而下降的现象。
压缩（Compaction）：Harness 层面的响应——在接近限制时智能卸载上下文，而非让 API 报错或静默丢弃消息。
工具调用卸载：防止大型工具输出淹没上下文窗口。Harness 可以在结果到达模型前进行摘要、截断或缓存。
6. 编排与 Hooks
生产 Agent 在 Harness 层面需要的七种行为：
- 工具输出协议：一个输出，多种渲染（UI vs 模型上下文）
- 会话状态：可查询的视图，涵盖失败计数、已尝试方法和循环检测
- 系统提醒：三个级别（系统消息种子、附加到用户消息、绑定特定工具）
- 停止条件：与会话状态集成，而非孤立标志
- 工具强制：序列规则、确认门、速率限制、自动操作
- 注入队列：上下文注入的优先级、批处理和去重
- Hooks：在每个阶段自定义执行
框架将这七种全部留给你。Harness 是这些决策的所在。
Why Frameworks Alone Aren't Enough
生产失败模式是 Harness 失败
| 失败 | 原因 |
|---|---|
| maxSteps 存在但与会话状态脱节 | Agent 循环，因为 Harness 没有与行为绑定的停止条件 |
| 30 分钟后上下文腐烂 | 框架没有导致它，Harness 没有预防它 |
| 大文件读取淹没上下文窗口 | 框架正确执行了工具，Harness 没有过滤输出 |
2025-2026 的转变
Harness 开始与模型一起从第一天就在循环中训练：
- Claude Code
- Codex
- Cursor
这些产品中实现的 Agentic 设计模式不是事后添加的，而是 Harness 设计的一部分。
How to Build or Choose a Harness
六个关键决策：
1. 执行环境
| 选项 | 特点 | 适用场景 |
|---|---|---|
| 本地 | 快速、便宜 | 个人开发 |
| Docker | 隔离，无云开销 | 小团队 |
| 云沙箱 | 并行工作负载扩展 | 生产部署 |
2. 工具表面积
从小型、经过良好测试的工具集开始，然后添加 Bash 作为通用逃生舱口。每个预配置工具都是你需要维护的表面。
3. 状态与记忆策略
文件系统是 Agent 拥有的最持久的状态存储。用它作为真相来源：
- AGENTS.md 用于持久记忆
- Git 用于版本控制和回滚
- 两个 Agent 需要协调时，通过文件协调
4. 长时程连续性
Ralph Loop（Geoffrey Huntley 提出）：Agent 将每个任务视为重复循环——
- 每次会话开始时写规划文件
- 执行一个任务
- 解决任何失败
- 在上下文重置前更新文件
5. 验证循环
运行自己测试套件、检查日志、观察浏览器状态的 Agent 在向人类交接前捕获更多错误。
6. 团队访问
- 个人 Harness：为单个开发者设计
- 团队 Harness：需要协作层——谁能触发 Agent、谁能看到它们在做什么、谁能干预
生产级 Harness 的 12 个组件（扩展框架）
根据 Anthropic、OpenAI、LangChain 及社区实践的总结，一个生产级 Agent Harness 可细分为 12 个独立组件：
1. 编排循环（Orchestration Loop）
实现思考-行动-观察（TAO/ReAct）循环。复杂性不在循环本身，而在循环管理的所有东西。Anthropic 将其运行时描述为"哑循环"——所有智能在模型里，harness 只管理回合。
2. 工具（Tools）
Agent 的手。处理注册、模式验证、参数提取、沙盒执行、结果捕获及格式化。Claude Code 提供六类工具：文件操作、搜索、执行、网络访问、代码智能和子智能体生成。
3. 记忆（Memory）
- 短期记忆：单个会话内的对话历史
- 长期记忆：跨会话持久化（CLAUDE.md、MEMORY.md、JSON 存储、SQLite/Redis Sessions）
- 关键原则：Agent 把自己的记忆当作"提示"，在行动前会对照实际状态验证
4. 上下文管理（Context Management）
核心问题是上下文腐烂：关键内容落在窗口中间位置时，模型性能下降 30% 以上。
生产策略：
- 压缩：总结对话历史，保留架构决策和未解决 bug
- 观察遮蔽：隐藏旧的工具输出，但保持工具调用可见
- 即时检索：维护轻量级标识符，动态加载数据
- 子智能体委托：每个子智能体广泛探索，只返回 1000-2000 token 摘要
5. 提示词构建（Prompt Construction）
分层组装：系统提示词 → 工具定义 → 记忆文件 → 对话历史 → 当前用户消息。
OpenAI Codex 使用严格优先级栈：服务器控制的系统消息（最高）→ 工具定义 → 开发者指令 → 用户指令（AGENTS.md，32 KB 限制）→ 对话历史。
6. 输出解析（Output Parsing）
现代 harness 依赖原生工具调用。结构化输出通过 Pydantic 模型约束。边缘情况使用 RetryWithErrorOutputParser 等传统方法。
7. 状态管理（State Management）
- LangGraph：类型化字典流经图节点，reducer 合并更新，检查点支持中断恢复和时间旅行调试
- OpenAI：四种互斥策略（应用程序内存、SDK 会话、Conversations API、previous_response_id 链接）
- Claude Code：git 提交作为检查点，进度文件作为结构化草稿本
8. 错误处理（Error Handling）
10 步流程，每步 99% 成功率，端到端成功率仅约 90.4%。错误快速复合。
LangGraph 区分四种错误：
- 瞬态：带退避重试
- LLM 可恢复：将错误作为 ToolMessage 返回，让模型调整
- 用户可修复：中断等待人工输入
- 意外：冒泡用于调试
9. 防护栏和安全（Guardrails and Safety）
OpenAI SDK 实现三个级别：输入防护栏、输出防护栏、工具防护栏。"绊线"机制触发时立即停止 agent。
Anthropic 在架构上将权限执行与模型推理分离：模型决定尝试什么，工具系统决定允许什么。
10. 验证循环（Verification Loops）
区分玩具演示和生产 agent 的关键：
- 基于规则的反馈：测试、linter、类型检查器
- 视觉反馈：Playwright 截图用于 UI 任务
- LLM 作为评判者：单独子智能体评估输出
Claude Code 创建者 Boris Cherny 指出：给模型验证其工作的方法，质量提高 2-3 倍。
11. 子智能体编排（Subagent Orchestration）
Claude Code 支持三种执行模型：Fork（字节相同副本）、Teammate（基于文件的邮箱通信）、Worktree（独立 git 分支）。
OpenAI SDK 支持智能体作为工具和交接。LangGraph 将子智能体实现为嵌套状态图。
12. 循环运作：七步演练
- 提示词组装：系统提示词 + 工具模式 + 记忆文件 + 对话历史 + 当前消息
- LLM 推理：生成文本、工具调用请求或两者
- 输出分类：无工具调用则结束；有则执行；交接则更新当前 agent
- 工具执行：验证参数、检查权限、沙盒执行、捕获结果
- 结果打包：格式化为 LLM 可读消息，错误作为错误结果返回
- 上下文更新：结果附加到对话历史，接近限制时触发压缩
- 循环：返回步骤 1，直到终止条件触发
终止条件：无工具调用的响应、超过最大回合限制、token 预算耗尽、防护栏触发、用户中断、安全拒绝。
真实框架实现对比
| 框架/Harness | 核心模式 | 特点 |
|---|---|---|
| Claude Agent SDK | query() 暴露 harness，流式消息异步迭代器 |
"哑循环"，所有智能在模型里 |
| OpenAI Agents SDK | Runner 类，三种模式（异步/同步/流式） | 代码优先，原生 Python 表达工作流 |
| Codex Harness | 三层架构：Codex Core → App Server → 客户端 | 所有界面共享同一 harness |
| LangGraph | 显式状态图（llm_call → tool_node → 条件边） | 从 AgentExecutor 演变而来，解决扩展性问题 |
| CrewAI | 基于角色的多智能体架构（Agent + Task + Crew） | Flows 层添加确定性骨干 |
| AutoGen | 对话驱动编排，三层架构 | 五种编排模式：顺序、并发、群聊、交接、magentic |
脚手架隐喻与协同进化
建筑脚手架是临时基础设施，使工人能够建造无法触及的结构。关键洞察：建筑完成后，脚手架会被拆除。
随着模型改进，harness 复杂性应该降低。Manus 在六个月内重建了五次，每次重写都删除了复杂性。
协同进化原则：模型现在在循环中使用特定 harness 进行后训练。改变工具实现可能会降低性能，因为这种紧密耦合。
Harness 设计的"未来验证测试"：如果性能随着更强大的模型扩展而不增加 harness 复杂性，设计就是合理的。
定义每个 Harness 的七个决策
- 单智能体 vs. 多智能体：Anthropic 和 OpenAI 都建议首先最大化单个 agent。仅当工具过载超过约 10 个重叠工具或存在明显独立任务域时才拆分。
- ReAct vs. 计划-执行：ReAct 灵活但每步成本更高；计划-执行将规划与执行分离（LLMCompiler 报告快 3.6 倍）。
- 上下文窗口管理策略：基于时间的清除、对话总结、观察遮蔽、结构化笔记、子智能体委托。
- 验证循环设计：计算验证（测试、linter）提供确定性真相；推理验证（LLM 作为评判者）捕获语义问题但增加延迟。
- 权限和安全架构：宽松（快但有风险）vs 限制性（安全但慢）。
- 工具范围策略：更多工具通常意味着更差性能。Vercel 从 v0 中删除了 80% 的工具获得了更好结果。原则：暴露当前步骤所需的最小工具集。
- Harness 厚度：Anthropic 押注薄 harness 和模型改进；基于图的框架押注显式控制。
FAQ
Q: Agent Harness 和 Agent Framework 相同吗？
框架提供构建 Agent 的抽象：工具接口、记忆模式、链原语。Harness 是之上的生产就绪层，添加特定配置、约束和基础设施。LangChain 是框架，Claude Code 是可能内部使用 LangChain 的 Harness。
Q: 什么是 Harness Engineering？
设计和优化 AI Agent 系统非模型层的实践。涵盖工具设计、上下文管理、执行环境、记忆架构和编排逻辑。Terminal Bench 2.0 结果显示它是提升 Agent 性能的主要杠杆，通常比模型选择更有影响力。
Q: 简单 AI 聊天机器人需要 Agent Harness 吗？
如果你的聊天机器人维护对话历史，那个循环已经是原始 Harness。添加工具、记忆或多轮推理时，显式 Harness 设计就很重要了。
Q: 哪些 Agentic AI Framework 可以与 Harness 配合使用？
LangChain、LangGraph、CrewAI、AutoGPT、OpenAI Agents SDK 都在框架或运行时层操作。Claude Code、DeepAgents、Builder.io 等平台 Harness 位于其上，为特定用例配置这些框架。
Key Takeaway
模型包含智能。Harness 是让智能可靠、有状态、可随时间行动的东西。
同样的模型仅通过改变 Harness 就可以从 top 30 以外提升到 top 5 的基准位置。框架选择不如 Harness 设计重要。
Sources
- What's an Agent Harness? And how do I choose the best one?
- Agent Harness：让AI从聊天机器人变成真正的智能体 — 向阳乔木，12 组件生产级 harness 框架详解
- Original: What's an Agent Harness? And how do I choose the best one? (2026-04-11)
- LangChain Blog: The Anatomy of an Agent Harness
- Builder.io: Claude Agent Teams Explained