Guide des harnais : pour des harnais d'agents évolutifs lisibles, navigables et modifiables

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

July 14, 2026

Auteurs: Ruhan Wang, Yucheng Shi, Zongxia Li, Zhongzhi Li, Yue Yu, Junyao Yang, Kishan Panaganti, Haitao Mi, Dongruo Zhou, Leoweiliang

cs.AI

Résumé

La capacité d'un agent d'IA moderne ne dépend pas seulement de son modèle de base, mais aussi de son harnais, qui construit les invites, gère l'état, appelle les outils et coordonne l'exécution. À mesure que les modèles, les API, les environnements et les exigences évoluent, le harnais doit être continuellement modifié. Avant de pouvoir apporter un tel changement, un développeur ou un agent de codage doit identifier tous les emplacements de code qui implémentent le comportement cible. Cela est difficile car les harnais de production sont volumineux, fortement couplés et comportementalement distribués, tandis que les demandes de modification décrivent ce que le système devrait faire et les dépôts sont organisés par fichiers et modules. La recherche de code, l'indexation de dépôt et le traitement de longs contextes facilitent l'inspection, mais laissent toujours ce mappage comportement-code à reconstituer manuellement. La localisation des comportements constitue donc un goulot d'étranglement central dans l'évolution des harnais. Nous introduisons le Manuel du Harnais, une représentation centrée sur le comportement synthétisée automatiquement à partir d'une base de code de harnais via analyse statique et structuration assistée par LLM, reliant chaque comportement à son code source correspondant. Nous introduisons également la Divulgation Progressive Guidée par le Comportement (DPGC), qui guide les agents des comportements de haut niveau vers les détails d'implémentation pertinents et vérifie les emplacements candidats par rapport au code source actuel. Sur diverses demandes de modification provenant de deux harnais open-source, la planification assistée par le Manuel améliore la localisation des comportements et la qualité des plans d'édition tout en utilisant moins de jetons de planification, les plus grands gains étant obtenus sur les sites dispersés, les chemins rarement exécutés et les interactions entre modules. L'évolution de systèmes agentiques complexes dépend donc non seulement de la génération d'éditions, mais aussi de la détermination des endroits où ces éditions doivent être effectuées.

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.