Manual de Arneses: Haciendo legibles, navegables y editables los arneses de agentes en evolución

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

July 14, 2026

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

cs.AI

Resumen

La capacidad de un agente de IA moderno no depende solo de su modelo base, sino también de su entorno de ejecución, que construye indicaciones, gestiona el estado, invoca herramientas y coordina la ejecución. A medida que los modelos, las API, los entornos y los requisitos evolucionan, el entorno debe modificarse continuamente. Antes de que se pueda realizar dicho cambio, un desarrollador o agente de codificación debe identificar todas las ubicaciones de código que implementan el comportamiento objetivo. Esto es difícil porque los entornos de producción son grandes, están fuertemente acoplados y distribuidos conductualmente, mientras que las solicitudes de modificación describen lo que el sistema debería hacer y los repositorios están organizados por archivos y módulos. La búsqueda de código, la indexación de repositorios y el procesamiento de contexto largo facilitan la inspección, pero aún dejan que esta correspondencia entre comportamiento y código sea recuperada manualmente. Por lo tanto, la localización de comportamientos es un cuello de botella central en la evolución del entorno. Introducimos el Harness Handbook, una representación centrada en el comportamiento sintetizada automáticamente a partir de un código base del entorno mediante análisis estático y estructuración asistida por LLM, vinculando cada comportamiento con su fuente correspondiente. También introducimos la Divulgación Progresiva Guiada por el Comportamiento (BGPD por sus siglas en inglés), que guía a los agentes desde comportamientos de alto nivel hasta detalles de implementación relevantes y verifica las ubicaciones candidatas contra el código fuente actual. En diversas solicitudes de modificación de dos entornos de código abierto, la planificación asistida por el Handbook mejora la localización de comportamientos y la calidad del plan de edición utilizando menos tokens de planificación, con las mayores ganancias en sitios dispersos, rutas raramente ejecutadas e interacciones entre módulos. La evolución de sistemas agénticos complejos depende, por lo tanto, no solo de generar ediciones, sino también de determinar dónde deben realizarse esas ediciones.

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.