06_Harness

一、基础概念

01 什么是 Harness Engineering？⭐⭐⭐

Harness Engineering 则是在 Agent 之上构建一套“约束与反馈系统”。它通过约束 Agent 的行为、检查 Agent 的结果，并根据反馈不断修正执行过程，让 Agent 更安全、稳定、更可靠地完成任务。

"Harness" 本意是马具，把马的力气引到正确方向上。拿来类比 AI Agent 非常合适：LLM 有很强的生成能力，但执行过程中容易跑偏，需要 Harness 进行约束和引导。

02 为什么需要 Harness 呢？⭐⭐

Harness 是 Agent 的约束与反馈系统，让 Agent 不仅能完成任务，还能稳定、可靠地完成任务。

03 Harness 和 Agent Engineering 有什么区别？⭐⭐⭐

Agent Engineering 是围绕 LLM 构建具有自主性的智能体系统，通常涉及任务规划、工具调用和记忆系统等；Harness 则是建立在 Agent 之上的一套“约束与反馈系统”。

04 为什么 Coding Agent 尤其需要 Harness？

Coding Agent 不仅生成代码，还会读写文件、执行命令和运行测试，具有更广泛的操作权限，因此需要 Harness 限制其操作范围，并通过测试结果持续反馈和修正。

05 Harness 和传统 CI/CD、Agent Framework 有什么区别？

Agent Framework 负责构建 Agent，CI/CD 负责按固定流程验证和交付代码，而 Harness 负责在 Agent 运行时提供约束、检查结果，并根据反馈不断修正执行过程。

二、Harness 的核心组成

01 Harness 通常由哪些模块组成？⭐⭐⭐

Harness 通常包括上下文工程、工具系统、执行编排、记忆与状态、评估与观测、约束与恢复。

上下文工程：围绕当前任务目标，动态筛选、组织和管理 Agent 的上下文信息。
工具系统：提供和管理工具，包括工具注册、参数校验、权限控制以及工具调用结果处理。
执行编排：控制 Agent 如何拆分任务，以及按照什么顺序执行任务。
记忆与状态：维护任务进度、中间结果、短期上下文和长期记忆。
评估与观测：通过日志、轨迹、测试结果和质量指标，了解 Agent 做了什么、结果是否正确，以及问题出在哪一步。
约束与恢复：限制 Agent 的操作范围，并在执行失败、结果不符合预期或陷入循环时，进行重试、回滚、重新规划或人工介入。

三、上下文工程

01 为什么需要上下文工程？⭐⭐⭐

随着任务复杂度提升，单靠优化指令已经不够，还需要在有限的上下文窗口内，动态筛选和组织准确、及时的信息，从而提升模型的推理、工具调用和任务执行效果。

Context Engineering（上下文工程）是围绕 LLM 的任务目标，动态构建、筛选、组织和管理上下文信息的一套工程方法。它关注的不只是 Prompt 怎么写，还包括向模型提供哪些信息、以什么顺序提供，以及如何控制上下文的长度和质量。

02 如何为 Agent 准备有效的上下文？| 上下文工程怎么去做？

为 Agent 准备有效的上下文，核心不是把尽可能多的信息塞给模型，而是围绕当前任务，动态提供相关、准确、及时且结构清晰的信息。

通常需要先明确任务目标，再按优先级组织系统指令、任务要求、项目背景、对话历史、相关知识和工具结果；对于过长或无关的内容，要进行筛选或者摘要压缩，避免上下文膨胀和无关信息干扰。同时，还要保证上下文来源可靠，在执行过程中根据任务进展动态更新上下文信息。

有效的上下文 = 在正确的时间，以正确的结构，给 Agent 正确且适量的信息。

四、工具系统

01 如何设计 Agent 的工具和工具权限？⭐⭐⭐

设计 Agent 工具时，应遵循原子性、自描述、可组合三大原则。

原子化：每个工具只负责一项明确功能（如 read_file 只读文件，write_file 只写文件），避免设计功能过于复杂的“万能工具“导致行为不可控；
自描述：通过标准 Schema（如 JSON Schema）清晰声明工具名称、作用、入参、出参及副作用，让 Agent 能自主理解并选择调用。
可组合：多个简单工具可以通过编排完成复杂任务，所有工具返回统一格式（状态码 + 结构化数据），便于 Agent 解析。

权限设计应遵循最小权限原则，按操作风险将工具分级（读 < 写 < 执行 < 删除），这样可以实现 Agent 运行时能力边界的动态收缩，同时通过白名单明确 Agent 可调用的工具范围，即使处于高等级权限，未列入白名单的工具依然不可调用。

02 如何限制 Agent 的操作范围？⭐⭐⭐

限制 Agent 的操作范围，核心是为它设置明确的资源边界、权限边界和行为边界。

资源边界：限制 Agent 的文件访问范围，例如只能操作指定工作目录；
权限边界：按照读、写、执行、删除等风险等级分配权限，高危操作默认禁止或需要人工确认；
行为边界：通过白名单、参数校验、沙箱隔离和资源限制，防止 Agent 执行危险操作或消耗过多资源；

限制 Agent 的本质，是让它只能在“允许的资源、权限和行为范围”内执行任务。

03 Harness 如何管理 Agent 的工具系统？⭐⭐⭐

Harness 通常通过工具注册、Schema 描述、调用分发、参数校验和结果处理来管理 Agent 的工具系统。

首先，为每个工具声明名称、用途、输入参数、输出格式和副作用，让 Agent 能够理解并选择工具；然后由 Harness 负责校验参数、分发调用、统一处理返回结果和错误信息，并将执行结果反馈给 Agent。

至于工具是否允许调用、能访问哪些文件、是否需要人工确认，则属于权限和操作范围控制。

Harness 不负责实现具体业务工具，而是负责让 Agent 能够正确、稳定地发现、调用和处理工具。

五、执行编排

01 如何管理 Agent 的任务状态和执行流程？⭐⭐⭐

我们可以把任务对应的执行计划和执行状态显示的建模出来，并为每个步骤记录任务目标、前置条件、预期结果和执行状态。执行过程中，根据每一步的结果动态推进或重新规划后续步骤。

执行计划负责描述“要做什么”，执行状态负责记录“做到哪一步”，动态重规划负责决定“接下来怎么做”。

02 如何避免 Agent 陷入重复执行或无限循环？⭐⭐⭐

首先，为任务设置最大执行步数、最大重试次数和超时时间；

其次，记录 Agent 已经执行过的操作及其结果。如果 Agent 反复执行相同操作，或者多次执行后任务状态仍然没有变化，就说明它可能陷入了循环，此时应及时停止并采取重新规划、降低任务粒度、回滚到检查点或请求人工介入等措施。

同时为任务设计明确的完成条件和失败条件，避免 Agent 不知道什么时候应该停止。

防止循环的核心是：限制执行次数，检测状态变化，定义终止条件，必要时及时交接。

六、评估与观测

01 如何观测和定位 Agent 的执行问题？

需要记录完整的执行轨迹，包括任务目标、上下文、模型调用、工具调用相关信息、状态变化和错误日志。出现问题时，沿着“上下文、模型决策、工具调用、工具结果、验证结果”逐步排查，定位具体失败环节。

比如 Coding Agent 要修复一个接口 Bug，但最终测试仍然失败，通过执行轨迹可以看到：

Agent 正确读取了任务和相关代码；
选择了正确的测试命令；
测试日志提示数据库字段类型错误；
Agent 修改代码时，却没有读取数据库模型，错误地修改了 API 层参数；
再次测试仍然失败。

因此，问题不在任务理解或工具调用，而在于 上下文准备不完整，导致 Agent 做出了错误修改。后续可以补充数据库模型到上下文，并要求修改前先检查相关 schema。

02 如何验证 Coding Agent 生成的代码是否正确？⭐⭐⭐

Coding Agent 生成代码后，通常采用静态检查、自动化测试和变更审查三层验证。

第一层是静态检查，包括代码格式、类型检查、Lint 检查和安全扫描，用于发现明显的代码质量和安全问题。

Lint 检查是一种静态代码分析工具，用来自动发现代码中的潜在问题和不规范写法。

第二层是自动化测试，通过单元测试验证核心函数逻辑是否正确，通过集成测试验证模块之间的协作；如果涉及完整业务流程，还需要运行端到端测试。

第三层是变更审查，通过检查 Git diff，确认修改范围符合预期，没有修改无关文件，也没有引入明显风险

如果验证失败，Harness 会将测试结果、错误堆栈和失败原因反馈给 Agent，让 Agent 针对问题进行代码修复，然后重新执行验证。同时设置最大迭代次数，避免 Agent 无限修改；多次失败后则停止执行并交由人工 Review。

验证闭环是：生成代码 → 自动检查 → 反馈错误 → Agent 修复 → 再次验证。

七、约束与恢复

01 Agent 执行失败后，如何通过反馈进行修正？⭐⭐⭐

Harness 首先记录失败步骤、工具调用参数、错误信息和当前任务状态等信息，然后将这些信息整理成明确的反馈交给 Agent，让 Agent 判断失败原因并修改后续计划。修正后重新执行失败步骤，并再次进行验证。

核心流程：记录失败 → 分析原因 → 修改计划 → 重新执行 → 再次验证。

02 如何设计 Agent 的自动重试、回滚和错误恢复？

首先根据错误类型决定处理方式：临时性错误可以自动重试，参数或逻辑错误需要让 Agent 修正后再试，状态已经被破坏时则回滚到最近的检查点。与此同时，需要设置最大重试次数、超时时间和最大执行步数，避免 Agent 无限执行；多次失败后应停止任务并请求人工介入。

03 如何判断 Agent 是否真正完成了任务？

不能只看 Agent 是否输出了“任务完成”，而应该根据预先定义的完成条件进行验证。例如代码任务需要通过测试、类型检查和代码审查，文件修改任务需要确认目标文件和内容符合要求，部署任务需要检查服务是否正常运行。

只有当所有关键验收条件都满足后，Harness 才将任务标记为完成；如果验证失败，就继续修正、执行，验证，多次失败则请求人工确认等操作。

八、Agent 评测 ⭐⭐⭐

01 为什么 Agent 评测需要体系化？

Agent 的输入、输出、执行路径和系统状态都具有不确定性，单次运行成功并不代表系统稳定可靠。因此，Agent 评测不能只看最终答案，还要结合执行轨迹、工具调用、任务状态和多次运行结果，持续发现问题并改进。

02 Agent 评测需要关注哪些维度？

Agent 评测不能只看最终答案，而要从结果、过程和工程指标，稳定性多个方面衡量。

结果：任务是否完成，答案是否正确；
过程：规划、工具调用和执行路径是否合理；
稳定性：同一任务多次运行是否能够持续成功；
工程指标：耗时、Token 消耗、工具调用次数和人工介入率。

03 如何设计 Agent 的评测数据集？

评测集不应该只是线上数据的随机抽样，而应该围绕核心业务流程、高风险场景和典型失败模式设计。通常先构建一组稳定、可复用的 Golden Set，再补充边界集、对抗集、线上回流集和历史 Badcase 集。

04 如何评估一个 Agent 是否稳定？

不能只看单次成功率，还要重复运行同一个任务，观察：

至少一次成功率：多次运行中只要成功一次即可；
连续成功率：多次运行都成功才算通过。

前者反映 Agent 有没有完成任务的能力，后者反映它是否稳定可靠。生产系统更应该关注连续成功率。

05 Agent 的评估器应该如何选择？

能用确定性规则判断的内容，优先使用规则评估，例如工具是否调用、参数是否正确、状态是否满足要求；涉及语言质量和策略合理性的内容，可以使用 LLM-as-Judge；高风险、低置信度或规则与模型结论冲突的样本，则交给人工复核。

06 如何评估 Agent 的多轮对话能力？

不能只评估单轮回答，而应该同时观察：

Turn：每一轮回复是否正确；
Session：整段对话是否解决用户问题；
Trace：执行过程和工具调用是否合理；
Outcome：最终业务结果是否达成。

多轮对话中，最终目标是否完成比每一轮回答是否流畅更重要。

07 如何分析 Agent 的 Badcase？

Badcase 分析不能只看最终错误，而要结合完整执行轨迹，依次排查用户意图识别、上下文管理、知识检索、工具选择、参数构造、业务规则理解和结果生成等环节，最终将问题定位到具体模块和可修复原因。

核心流程：收集证据、缩小范围、定位责任、生成修复动作。

08 Agent 评测如何形成闭环？

评测系统不应该只输出分数，而应该将失败样本沉淀为 Badcase，分析失败原因并修复系统；然后把原来的失败样本保留为固定的回归用例，在后续版本中重复运行，验证问题是否解决，以及是否引入新的问题。

完整闭环：执行评测 → 发现问题 → 定位原因 → 生成修复 → 回归验证 → 线上观察。

09 如何评估一次版本升级是否真的变好了？

需要将新旧版本放在同一套评测集上进行对比，同时关注核心任务成功率、连续成功率、高风险问题数量、成本和线上业务指标。还要结合统计波动判断差异是否真实，避免把随机波动误认为能力提升。

10 Agent 评测结果应该输出什么？

评测结果不应只有 Pass/Fail 或一个总分，还应该包含问题分类、失败现象、执行轨迹、关键证据、责任模块、置信度和修复建议。这样评测结果才能直接进入研发、配置、知识库或运营流程。