Руководство по харнесу: как сделать эволюционирующие агентные харнесы читаемыми, удобными для навигации и редактирования

Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable

July 14, 2026

Авторы: Ruhan Wang, Yucheng Shi, Zongxia Li, Zhongzhi Li, Yue Yu, Junyao Yang, Kishan Panaganti, Haitao Mi, Dongruo Zhou, Leoweiliang

cs.AI

Аннотация

Современный ИИ-агент зависит не только от своей базовой модели, но и от обвязки (harness), которая формирует промпты, управляет состоянием, вызывает инструменты и координирует выполнение. По мере эволюции моделей, API, сред и требований обвязку приходится постоянно модифицировать. Прежде чем внести такое изменение, разработчик или агент-кодировщик должен определить все участки кода, реализующие целевое поведение. Это сложно, поскольку производственные обвязки велики, тесно связаны, а их поведение распределено, тогда как запросы на модификацию описывают, что система должна делать, а репозитории организованы по файлам и модулям. Поиск кода, индексирование репозиториев и обработка длинного контекста облегчают инспекцию, но по-прежнему оставляют задачу ручного восстановления соответствия между поведением и кодом. Таким образом, локализация поведения является центральным узким местом в эволюции обвязки. Мы представляем Harness Handbook — ориентированное на поведение представление, автоматически синтезируемое из кодовой базы обвязки с помощью статического анализа и структурирования при помощи языковых моделей, связывающее каждое поведение с соответствующим исходным кодом. Мы также вводим метод прогрессивного раскрытия, направляемого поведением (Behavior-Guided Progressive Disclosure, BGPD), который ведёт агентов от высокоуровневого поведения к релевантным деталям реализации и проверяет кандидатные участки на соответствие текущему исходному коду. При решении разнообразных запросов на модификацию для двух обвязок с открытым исходным кодом планирование с помощью Handbook улучшает локализацию поведения и качество плана правок, используя при этом меньше токенов планировщика; наибольший выигрыш достигается на разрозненных участках, редко выполняемых путях и межмодульных взаимодействиях. Таким образом, эволюция сложных агентных систем зависит не только от генерации правок, но и от определения того, где эти правки должны быть внесены.

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.