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、谁能看到它们在做什么、谁能干预

Skill 工程化设计：从提示词到执行环境（腾讯实践）

来源：<a href="/wiki/raw/to-learn/当我把-ai-变成一个"算法"：skill-工程化设计的心路历程.md" class="wikilink">当我把 AI 变成一个"算法" — 腾讯 peihanyu

当规则写到 200 行，Agent 开始跳步骤、串字段、不问就执行。问题不在模型，在结构——LLM 的注意力不像人类读手册，更像实习生第一天被灌完全部规章后去干活，只记住开头几条和最后一条。真正该问的问题：怎么设计一个让 AI 在每个时刻都只需要关注最少信息的执行环境？

把 Agent 当成算法用

Agent 的理想形态：输入自然语言，输出结构化参数。中间推理保留不确定性，但推理之外的一切——流程顺序、数据格式、API 调用、状态管理——全部交给确定性程序。不是驯服 AI，而是为它构建一个天然适合流淌的河道。

CLI 作为确定性执行层

角色	Agent（大脑）	CLI（手脚）
做什么	理解意图、收集参数、组织回复	调 API、写文件、管状态
沟通方式	只输出 JSON 参数	只返回 JSON 结果
不确定性	有（被限定在决策范围内）	无（相同输入 = 相同输出）

Agent 的不确定性被 CLI 的确定性包裹住。Agent 不再自己拼 HTTP 请求（漏 header、字段名拼错），而是说 "调用 create_project，参数：name=foo, host=bar.com"，CLI 负责剩下一切。

信息获取的三层分离

当 Skill 背后有 50 个工具时，全量写进 SKILL.md 会上下文爆炸，拆成 reference 文件又让 Agent 自己判断该读哪个——这是一层新的不确定性。

解决方案：CLI 强制接管，Agent 不读文件。 Agent 的信息获取路径被 CLI 完全托管：

层级	内容	Agent 何时可见	存储
索引层	工具名 + 一句话描述	始终可见	`tools-index.md`（50 行表格）
元数据层	字段名、类型、必填、枚举值	用户请求某工具时按需加载	`tools/<name>.meta`
规则层	IGNORE/NOTE/ENUM 注解	融合在元数据输出中，Agent 不直接看到	`tools/<name>.rules`

Agent 面对 50 个工具时，上下文里只多了一张 50 行的表格。等用户真的要用时，才通过 --meta-json 按需获取。

Discover：热更新与自动生成规则

每次 Skill 被激活，CLI 执行 discover：

通过 MCP 调用后端 tools/list，拿到最新工具列表
与本地缓存做增量对比（新增/移除）
为每个新工具生成独立的 .meta 参数文件
自动提取枚举值写入 .rules 文件的 ENUM 行
自动识别系统字段（如 id、update_time），生成 IGNORE 规则
重新生成 tools-index.md

Agent 唯一感知到的就是"增加了 2 个工具"。连新工具有几个参数都不知道——等真的要用时才按需获取。

Workflow 引擎

用户的真实需求从来不是"帮我调一个 API"，而是"帮我搭一套权限体系"。Workflow 把散落的工具串成可靠的流水线。

核心机制：

机制	说明
步进式披露	流程是文件系统上的一组 Markdown 步骤文件。Agent 通过 CLI 交互，任意时刻只看到"当前这一步"
Gate 门禁	每个步骤文件头部声明 `gate schema`，精确定义本步需要提交什么。required 字段没给就拒绝推进，schema 没声明的字段直接丢弃
状态持久化	CLI 把流程运行状态写到磁盘 JSON（`.state`）。任何会话、任何模型——调 `--current` 就能从断点续上
模板变量	步骤间数据流由 CLI 管理：`{{gate.<step-id>.<field>}}` 引用前序交互步骤的输入，`{{result.<step-id>.<path>}}` 引用前序自动步骤的 API 返回值
三种步骤类型	`interactive`（Agent 与用户交互）、`automated`（CLI 内部自动执行）、`notification`（展示信息）

Workflow 是文件，不是代码——业务人员改 Markdown 就能扩展能力，排序即逻辑（文件名前缀决定顺序），版本管理天然支持 git diff。

自举闭环

新建 Workflow 本身也是"多步骤、固定格式、确定性"的流程。于是做第二个 Skill workflow-creator：Agent 做需求分析（拆步骤、设计 gate schema、规划数据流），配套 CLI 做文件生成（init 创建骨架、add-step 追加步骤、validate 校验完整性）。

系统形成自洽闭环：设计（Agent + workflow-creator）→ 构建（CLI 写文件）→ 执行（运行时 CLI 工作流引擎）→ 用户提出新需求 → 回到设计。

Anthropic 官方 Harness 扩展点（2026-05-14）

来源：Anthropic — How Claude Code works in large codebases

Anthropic 将 Claude Code 的 harness 定义为 5 个扩展点 + 2 个额外能力，并强调"harness 的重要性不亚于模型本身"。

扩展点	功能	何时加载	常见误用
CLAUDE.md	上下文文件，Claude 每会话自动读取	每会话	把可复用 expertise 塞进 CLAUDE.md（应放 skill）
Hooks	关键时刻触发的脚本	事件驱动	用 prompt 做应自动运行的事
Skills	特定任务类型的打包指令	按需，相关时加载	全塞进 CLAUDE.md
Plugins	打包的 skills + hooks + MCP 配置	配置后始终可用	让好的 setup 停留在部落知识
MCP servers	连接外部工具和数据源	配置后始终可用	基础没打好就建 MCP
LSP integrations	通过语言服务器实现符号级导航	配置后始终可用	以为自动生效
Subagents	隔离的 Claude 实例，独立上下文	调用时	探索和编辑在同一个 session

关键洞察：

CLAUDE.md 优先：根文件给大局观，子目录文件给本地约定。保持聚焦，防止性能拖累。
Hooks 的自我改进价值：stop hook 可在 session 结束时反思并提议 CLAUDE.md 更新；start hook 可动态加载团队特定上下文。
Skills 的路径作用域：可绑定到特定目录，在 monorepo 中避免无关加载。
LSP 是多语言代码库最高价值投资：grep 在大型代码库中返回数千匹配，LSP 只返回同一符号的引用。

生产级 Harness 的 12 个组件（扩展框架）

根据 Anthropic、OpenAI、LangChain 及社区实践的总结，一个生产级 Agent Harness 可细分为 12 个独立组件：

1. 编排循环（Orchestration Loop）

实现思考-行动-观察（TAO/ReAct）循环。复杂性不在循环本身，而在循环管理的所有东西。Anthropic 将其运行时描述为"哑循环"——所有智能在模型里，harness 只管理回合。

2. 工具（Tools）

Agent 的手。处理注册、模式验证、参数提取、沙盒执行、结果捕获及格式化。Claude Code 提供六类工具：文件操作、搜索、执行、网络访问、代码智能和子智能体生成。

工具设计的十条原则

来源：AI Agent 工具设计原则 — LinklyAI

工具设计不是 REST API 的薄封装，而是直接影响 Agent 任务成功率的核心杠杆。Block 的 Linear MCP 从 30+ 工具精简到 2 个，GitHub Copilot 从 40 个砍到 13 个，任务成功率提升 2–5 个百分点，延迟降低 400ms。

1. 面向结果设计，不是面向接口 把多个内部调用合并成面向任务的工具。反面：get_user → list_orders → get_shipment；正面：track_order(email) 一次搞定。

2. 控制工具数量（5–15 个 / Server） 超过 20 个工具，模型选择准确率急剧下降。5 个 MCP Server 可能在用户开口前就消耗 55K token。做法：一个 Server 只做一件事，不常用的用动态发现（Tool Search）延迟加载。

3. 工具描述 = Prompt 好的描述包含六个要素：用途、何时使用、何时不使用、参数说明、限制、示例。把它当作给新员工的入职文档。

4. 命名清晰，带命名空间 格式：{服务}_{动词}_{名词}，如 slack_send_message。多个 Server 并存时，不带前缀的 create_issue 会让模型困惑。

5. 参数扁平化，用枚举约束 参数放顶层，不要嵌套对象；有限选项用 enum；用 JSON Schema 的 minimum、maximum、pattern 做约束；提供合理默认值。

6. 输出精简，为 token 效率优化 Claude Code 默认截断工具输出到 25,000 token。Block 对超过 400KB 的文件直接报错。

分页：返回 limit、offset、has_more、total_count
在源头过滤，不要把全量数据丢给模型筛
去掉低价值字段（UUID、内部 ID）
提供详略开关 response_format: concise | detailed
Markdown/XML 通常比原始 JSON 更省 token

7. 用语义标识符，不用 UUID 把 UUID 解析成人类可读的名称再返回。Anthropic 实测显示这能显著减少后续调用中的幻觉。

8. 错误信息要教 Agent 怎么修复 反面：返回 Python 堆栈跟踪。正面："未找到用户。请尝试用邮箱搜索。示例：search_user(email='jane@acme.com')"。好的错误信息包含：出了什么问题、期望是什么、正确示例、1–2 个修复建议。

9. 用评估驱动迭代 Anthropic 的元建议：把工具设计当作非确定性工程，用 eval 驱动。生成几十个真实多步骤测试任务，记录每次调用、错误和 token 消耗；让模型分析对话记录找出描述不清、上下文缺失、冗余调用的地方；关注"模型没做什么"——沉默的遗漏比显式错误更重要。

10. 读写分离 一个工具要么只读，要么只写。MCP 规范的 readOnlyHint、destructiveHint 注解即为此设计，让用户/Agent 可以安全地批量授权只读工具。

十二个常见反模式

#	反模式	后果
1	API 一对一映射	每个端点一个工具，Agent 疲于编排
2	通用命名	`get_data`、`process_request` 让模型无从选择
3	模糊描述	`"获取数据"` 不提供任何上下文
4	嵌套参数	dict 套 dict，模型容易编造键名
5	返回所有字段	原样透传 API 响应，context 爆炸
6	到处是 UUID	后续调用全靠幻觉
7	读写混合	一个工具既查又改，权限无法细分
8	无分页无截断	context 溢出，模型放弃
9	原始异常堆栈	浪费轮次，无法恢复
10	工具过多	选择准确率随数量对数下降
11	工具太"聪明"	MCP Server 自己做推理，抢了模型的活
12	状态塞进返回值	大块 JSON blob 让客户端来回传递

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 进行后训练。改变工具实现可能会降低性能，因为这种紧密耦合。详见 Model-Harness-Fit。

Harness 设计的"未来验证测试"：如果性能随着更强大的模型扩展而不增加 harness 复杂性，设计就是合理的。

Tejas Kumar：Agent Harness 的六组件定义（2026-05-20）

来源：AI Agent 时代的工作革命 — 十期播客精华综述 — Tejas Kumar 在 IBM / Code with Claude 演讲

Tejas Kumar 将 Agent Harness 定义为模型周围的一切，为它提供现实接地的东西。他用登山安全带（harness）作比喻：登山者把自己固定在稳定的山体上，不会脱轨。

Harness 的典型组成部分

组件	说明	示例
工具注册表	读取文件系统、写入、执行 bash 等	Claude Code 的文件操作工具
模型选择	决定使用哪个模型完成特定任务	Tasklet 的多模型路由
上下文管理原语	自动压缩上下文，防止窗口溢出	按时间段分桶的摘要策略
护栏	max steps、max messages 等硬约束	超过六步工具调用即终止
Agent 循环	围绕 Agent Loop 的外层循环或 M-loop	收集事件直到满足终止条件
验证步骤	跑 lint、跑测试、确定性检查	检查工具历史是否包含成功标记

关键演示：旧模型 + Harness = 新能力

Tejas 用 GPT-4.5 Turbo（2023 年旧模型）演示 Hacker News 点赞任务：

无 Harness：Agent 撒谎说成功了，实际上没登录
加护栏后：Agent 正确报告失败，不再幻觉
加登录处理器后：Harness 自动注入凭证，Agent 成功完成任务

"我一次都没动过 prompt，结果就彻底变了。"

这证明了 Harness 的独立性：同样的模型，仅通过添加 harness 层，行为可以从"幻觉失败"变为"可靠成功"。

Harness 演进时间线

年份	主题	特征
2025	Agent 之年	单个 Agent 能完成简单任务
2026	Harness 之年	Agent 需要可靠的护栏、工具、验证机制
2027	动态 Harness	Agent 执行任务前自动生成 Harness

Andrew Lee：Harness 从"缰绳"到"机甲"（2026-05-20）

来源：AI Agent 时代的工作革命 — 十期播客精华综述 — Andrew Lee, Tasklet CEO

Tasklet 过去六个月彻底重建，从工作流自动化工具变成通用 Agent 平台。核心变化：

上下文压缩架构

将聊天历史放进文件系统，发送给 LLM 的只是提示，告诉它文件系统里有什么：

时间段	保留策略
近期内容	完整保留（思考块、工具调用、响应）
中期内容	去掉思考块，截断工具响应
远期内容	基于 LLM 的摘要

Harness 的未来形态

从"缰绳"（约束）变成"机甲"（赋能）
目标不是限制模型能干什么，而是拓展它能干什么
需要存储、算力、API 连接、用户对话——"这里头涉及的东西非常多"

多模型策略

Tasklet 从 all-in Claude 转向模型中立平台，支持 Anthropic、OpenAI、Google、DeepSeek、Kimi。"押我们等于押住所有人。"

Yann Dubois：Harness 的临时性（2026-05-20）

来源：AI Agent 时代的工作革命 — 十期播客精华综述 — Yann Dubois, OpenAI Post-Training Frontiers

Yann Dubois 提出 Harness 的"临时性"悖论：

"现在 Harness 确实能显著提升模型能力"
"但考虑到能力进展非常快，我个人不会在 Harness 上压得太重"
"通用 Harness 行不通，Harness 更适合特定领域"
"如果我们冻结现有模型，真的去打磨 Harness，人们在每个领域都会真正感受到 AGI"
"但问题是，我们不会冻结模型"

核心共识：模型和 Harness 是"正交的"、"倍增的"关系——更好的模型 + 更好的 Harness = 指数级提升，但模型进步可能让某些 Harness 投资过时。

新璐的三层 Harness 框架（2026-05-05）

来源：十字路口播客 — 对谈来新璐

ShareAI 创始人新璐（Learn Claude Code，GitHub 5 万+星）将 Agent Harness 拆为三层：

层	职责	核心组件
1. 执行能力层	给模型提供 action 能力	CLI 工具、MCP 工具、文件增删读写搜索、浏览器、语言解释器。95% 任务配好文件系统+浏览器+解释器就够了
2. 上下文/状态层	管理模型的"工作记忆"和持久状态	system prompt、skills、memory、上下文卸载。模型上下文窗口满了必须接力——写文档记录进度，新 Agent 读取后继续
3. 编排/治理层	多 Agent 协调和权限隔离	串行/并行/权限隔离。测试 agent 不该有修改代码的权限

好 Harness 的两个标准

与模型的运行逻辑自洽：不自洽的例子——随意裁剪上下文导致 prompt cache 失效、随意修改 system prompt
与模型未来的能力进步正交：模型越强，Harness 不应成为束缚。反例：LangChain 每代必须做破坏性更新

核心排序：模型 > 上下文 > 工具

模型排第一（换更强的模型大概率就能提升）。上下文排第二（对用户来说上下文才是最重要的，也是我们能修改的）。工具排第三。

"More context, less control, zero control"

Claude Code 的设计哲学：给模型更多上下文和 action 能力，不要画状态图控制它。过去 LangChain/LangGraph 那种 prompt-node 流程图方法论在 Agent 模型时代越来越不适用。"模型才是 Agent"——Claude Code 淋漓尽致地体现了这一点。

最好的管理就是不要做管理——上下文压缩容易导致 KV Cache 失效。

定义每个 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 设计重要。