Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable
arXiv · HuggingFace · ▲199
摘要(原文)
The capability of a modern AI agent depends not only on its foundation model but also on its harness, which constructs prompts, manages state, invokes tools, and coordinates execution. As models, APIs, environments, and requirements evolve, the harness must be continually modified. Before such a change can be made, a developer or coding agent must identify all code locations that implement the target behavior. This is difficult because production harnesses are large, tightly coupled, and behaviorally distributed, while modification requests describe what the system should do and repositories are organized by files and modules. Code search, repository indexing, and long-context processing ease inspection, but still leave this behavior-to-code mapping to be recovered by hand. Behavior localization is therefore a central bottleneck in harness evolution. We introduce the Harness Handbook, a behavior-centric representation synthesized automatically from a harness codebase via static analysis and LLM-assisted structuring, linking each behavior to its corresponding source. We also introduce Behavior-Guided Progressive Disclosure (BGPD), which guides agents from high-level behaviors to relevant implementation details and verifies candidate locations against the current source. On diverse modification requests from two open-source harnesses, Handbook-Assisted planning improves behavior localization and edit-plan quality while using fewer planner tokens, with the largest gains on scattered sites, rarely executed paths, and cross-module interactions. Evolving complex agentic systems thus depends not only on generating edits, but also on determining where those edits should be made.
摘要(中译)
现代人工智能代理的能力不仅取决于其基础模型,还取决于其“ harness( harness:这里可理解为‘ harness(工具链/执行框架)’)”,它构建提示、管理状态、调用工具并协调执行。随着模型、API、环境和需求的发展,harness必须不断修改。在进行此类更改之前,开发人员或编码代理必须识别实现目标行为的所有代码位置。这很困难,因为生产harness规模大、耦合紧密且行为分散,而修改请求描述了系统应该做什么,且存储库按文件和模块组织。代码搜索、存储库索引和长上下文处理便于检查,但仍需要手动恢复这种行为到代码的映射。因此,行为定位是harness进化中的一个核心瓶颈。我们引入了Harness Handbook,这是一种以行为为中心的表示,通过静态分析和LLM(LLM:大语言模型)辅助结构化从harness代码库中自动合成,将每个行为链接到其对应的源代码。我们还引入了Behavior - Guided Progressive Disclosure(BGPD,行为引导的渐进式披露),它引导代理从高级行为到相关的实现细节,并根据当前源代码验证候选位置。在来自两个开源harness的多样化修改请求中,Handbook - Assisted规划提高了行为定位和编辑计划的质量,同时使用了更少的规划器令牌,在分散的站点、很少执行的路径和跨模块交互方面收益最大。因此,进化复杂的代理系统不仅取决于生成编辑,还取决于确定这些编辑应该在哪里进行。
背景剖析
背景剖析
1. 技术背景与真实需求
现代AI智能体(如工具调用型助手或自动化系统)的核心能力不仅依赖基础模型,还取决于其“ harness”(即协调模型、工具和环境执行任务的“控制层”)。这类系统被广泛用于处理复杂任务,例如网页交互、代码生成或数据操作。然而,随着模型更新、API变更或业务需求调整,harness必须持续迭代。开发者的核心痛点是:当需要修改某个功能(如优化工具调用逻辑或修复执行漏洞)时,如何快速定位到代码中所有相关的实现位置?传统方法依赖人工阅读代码库或编码代理逐段搜索,但在大型、高度耦合的harness中,这一过程效率极低且容易遗漏关键逻辑。
2. 先前方法的局限性
现有工具(如代码搜索、仓库索引或长上下文处理)虽能帮助浏览代码,但存在根本缺陷:它们按文件或模块组织信息,而修改请求描述的是“行为”(如“让智能体在查询失败时重试三次”)。开发者或代理需要手动将行为需求映射到具体代码,这一过程耗时且易出错。例如,一个看似简单的行为可能分散在多个函数或文件中,而编码代理受限于上下文长度,无法一次性分析全部代码,导致遗漏边缘场景或跨模块的交互逻辑。
3. 本文的解决思路
论文提出了“Harness Handbook”,一种以行为为中心的代码表示方法。它通过静态分析和LLM辅助结构化,自动从harness代码库中提取行为与代码的对应关系。例如,将“处理用户身份验证”这一行为直接链接到实现该功能的代码段。此外,引入“Behavior-Guided Progressive Disclosure(BGPD)”工作流,引导代理从高层行为逐步深入到具体实现细节,并验证候选代码是否匹配当前版本。这种方法将“行为→代码”的映射显式化,减少了人工或代理的推理负担。
4. 与前人工作的关键差异
此前方法主要优化代码库的可探索性(如生成代码摘要或索引),但未解决“行为到代码”的直接关联问题。本文的突破在于:
- 焦点转移:从“如何组织代码”转向“如何组织行为”,使开发者/代理能先理解需求对应的系统行为,再定位实现。
- 自动化构建:通过静态分析和LLM自动生成行为-代码映射,而非依赖人工标注或静态规则。
- 动态验证:BGPD工作流在规划阶段验证代码与行为的匹配性,避免过时或错误的修改建议。
实验表明,这种方法显著提升了行为定位准确性和编辑计划质量,尤其适用于分散逻辑或跨模块交互的场景。




