Harness-handboek: evoluerende agent-harnesses leesbaar, navigeerbaar en bewerkbaar maken

Samenvatting

De capaciteit van een moderne AI-agent hangt niet alleen af van zijn fundamentmodel, maar ook van zijn harnas, dat prompts construeert, toestand beheert, tools aanroept en de uitvoering coördineert. Naarmate modellen, API’s, omgevingen en vereisten evolueren, moet het harnas voortdurend worden aangepast. Voordat een dergelijke wijziging kan worden doorgevoerd, moet een ontwikkelaar of codeeragent alle codelocaties identificeren die het beoogde gedrag implementeren. Dit is moeilijk omdat productieharnassen groot, sterk gekoppeld en gedragsmatig verspreid zijn, terwijl wijzigingsverzoeken beschrijven wat het systeem moet doen en repositories georganiseerd zijn op bestanden en modules. Zoekacties in code, repository-indexering en verwerkingsprocessen met lange contexten vergemakkelijken de inspectie, maar laten het herstellen van deze gedrag-naar-code-toewijzing nog steeds aan handmatig werk over. Gedragslokalisatie vormt daarom een centrale bottleneck in de evolutie van harnassen. Wij introduceren het Harness Handbook, een gedragsgerichte representatie die automatisch wordt gegenereerd uit een harnascodebase via statische analyse en LLM-ondersteunde structurering, waarbij elk gedrag wordt gekoppeld aan de bijbehorende bron. Daarnaast introduceren wij Gedragsgestuurde Progressieve Onthulling (BGPD), die agenten leidt van gedragingen op hoog niveau naar relevante implementatiedetails en kandidaatlokaties verifieert aan de hand van de huidige bron. Bij diverse wijzigingsverzoeken uit twee open-source harnassen verbetert Handbook-ondersteunde planning de gedragslokalisatie en de kwaliteit van bewerkingsplannen, terwijl er minder planner-tokens worden gebruikt, met de grootste winst bij verspreide locaties, zelden uitgevoerde paden en cross-module interacties. Het evolueren van complexe agentische systemen hangt dus niet alleen af van het genereren van bewerkingen, maar ook van het bepalen waar die bewerkingen moeten worden uitgevoerd.

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.