让复杂智能体的代码可读可改,自动关联行为与实现位置。
Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable

- 用静态分析+大模型构建行为为中心的代码手册,自动链接行为与源码。
- 在分散、冷门路径上定位效率提升超30%,编辑方案更准确。
- 适合维护大型智能体系统的开发者或自动化工具使用。
现代AI智能体的能力不仅依赖基础模型,还取决于其协作者(harness),后者负责构造提示、管理状态、调用工具并协调执行。随着模型、API、环境和需求持续演进,协作者必须不断修改。但在修改前,开发者或编码代理需定位所有实现目标行为的代码位置——这很困难,因生产级协作者代码庞大、耦合紧密、行为分布零散,而修改请求描述的是系统应有行为,代码库却按文件和模块组织。尽管代码搜索、仓库索引和长上下文处理能辅助查看,行为到代码的映射仍需手动恢复。因此,行为定位成为协作者演进的核心瓶颈。本文提出「协作者手册」(Harness Handbook),通过静态分析与大模型辅助结构化,自动从协作者代码库中生成以行为为中心的表示,将每项行为与其对应源码连接。同时提出行为引导渐进披露(BGPD)机制,引导代理从高层行为逐步深入到相关实现细节,并验证候选位置与当前源码的一致性。在两个开源协作者的多样化修改请求测试中,手册辅助规划显著提升行为定位准确率与编辑计划质量,且使用的规划令牌数更少,尤其在行为分散、极少执行路径及跨模块交互场景下收益最大。因此,演化复杂智能体系统不仅需要生成修改,还需精准确定修改位置。
原文摘要 · Abstract (English)
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.
Thank you to arXiv for use of its open access interoperability. PaperDance 不是 arXiv 官方产品;中文卡片由大模型生成,请以原文为准。