约 7 分钟3 张卡

Agent Harness

Agent Harness 指包裹模型、让它能够完成任务的运行时：执行循环、工具定义与执行、上下文组装、状态持久化、权限与沙箱、结果验证和可观测性。同一个模型放进不同的 Harness，任务成功率可能差别很大。本文以编码 Agent 为例说明各模块的职责和它们之间的关系。

1. 面试核心

先记住这几条，再读正文

模型只负责根据上下文生成下一步；Harness 负责其余所有事情：决定给模型看什么、执行模型提出的动作、保存进度、阻止越权动作、判断是否完成。卡 · 模块与职责
核心模块可以按一次调用的链路记忆：上下文组装 → 模型调用 → 工具执行（含权限检查）→ 结果写回 → 状态保存 → 停止与验证。
设计编码 Agent 时，难点不在“能调用工具”，而在长任务的上下文、可验证的完成条件、失败恢复和安全边界。卡 · 模块与职责
上下文工程是 Harness 的一个模块。Harness 还包括执行、状态、权限、验证这些和上下文无关的部分。卡 · 模块与职责

2. 模块与职责

卡 · 什么是 Agent Harness？一个标准的 Harness 包含哪些核心模块？卡 · 如果让你从零设计一个 Coding Agent，你会怎么设计？卡 · Harness 和上下文工程有什么区别？模型变强后 Harness 还重要吗？

模块	职责	编码 Agent 中的例子
执行循环	调用模型、分发工具调用、判断停止	最大步数、超时、重复调用检测
工具层	定义工具契约，校验参数并执行	读文件、搜索、编辑、运行命令、测试
上下文组装	每轮选择放入窗口的信息	系统规则、仓库指令、相关代码、最近的工具结果
上下文压缩	窗口接近上限时整理历史	摘要旧对话，保留目标、已改文件和未解决错误
状态与会话	保存进度，支持中断后恢复	会话日志、待办列表、Git 提交作为检查点
权限与沙箱	区分读、写、执行、联网、发布的风险	写文件前确认，命令在容器或受限目录执行
验证	用外部证据判断完成	运行测试、类型检查、构建，失败时把输出写回
扩展机制	按需加载额外能力	Skills、MCP 服务器、子 Agent、Hook
可观测性	记录轨迹、用量和错误	每步的工具调用、耗时、Token、退出原因

这些模块和模型解耦：换模型时大部分 Harness 代码不变，但提示词、工具描述和预算参数需要重新评测。

3. 一次修改任务的链路

卡 · 什么是 Agent Harness？一个标准的 Harness 包含哪些核心模块？卡 · 如果让你从零设计一个 Coding Agent，你会怎么设计？

以“修复一个失败的单元测试”为例：

组装上下文：系统提示描述可用工具和规则；读取仓库指令（如 AGENTS.md）；用户描述的失败现象。
探索：模型调用搜索和读文件工具，定位测试和被测函数。Harness 对大输出截断或分页，避免一次读入整个仓库。
修改：模型提出编辑。Harness 检查路径是否在工作区内、是否需要用户确认，然后应用修改并返回 diff。
验证：模型调用测试命令，Harness 在沙箱中执行并返回退出码与关键输出。失败则继续循环。
保存进度：长任务中，Harness 把待办、已改文件和最近的测试结果写入会话状态；上下文压缩时这些信息必须保留。
停止：测试通过且模型给出总结，或触发步数、预算上限。

链路中真正保证结果可靠的是第 4 步：完成依据来自测试与构建输出，而不是模型声明。

4. 长任务的处理

卡 · 如果让你从零设计一个 Coding Agent，你会怎么设计？

单个上下文窗口装不下的任务，需要 Harness 把进度保存在窗口之外：

外部进度文件：用待办列表或进度文件记录已完成和剩余工作，新会话先读取它。
增量提交：每完成一个可验证的单元就提交，出错时可以回退，新会话也能从 Git 日志了解历史。
环境初始化脚本：让新会话能用一条命令启动服务和测试，不必重新摸索环境。
子 Agent：把搜索或独立子任务放到子 Agent 的独立上下文中，只把结论返回主循环，见多 Agent 协作。

5. 常见问题

5.1 Harness 和 Agent 框架有什么关系

LangGraph、Claude Agent SDK、OpenAI Agents SDK 等框架提供 Harness 的部分或全部模块，例如循环、状态检查点、工具注册和追踪。自研 Harness 通常出于对上下文策略、权限模型或部署环境的特殊要求。选型时比较的是这些模块是否满足需求，而不是框架名称。