🤖 AI

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

Questo articolo introduce l'Harness Handbook, una rappresentazione centrata sul comportamento e un metodo di Rivelazione Progressiva Guidata dal Comportamento (BGPD) che mappa automaticamente i requisiti comportamentali di alto livello alle specifiche posizioni nel codice sorgente, superando così il collo di bottiglia della localizzazione e migliorando l'efficienza e la qualità dell'evoluzione di complessi harness per agenti IA.

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

Pubblicato 2026-07-16

📖 4 min di lettura☕ Lettura da pausa caffè

CC BY 4.0

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

Articolo originale sotto licenza CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Questa è una spiegazione generata dall'IA dell'articolo qui sotto. Non è stata scritta né approvata dagli autori. Per precisione tecnica, consulta l'articolo originale. Leggi il disclaimer completo

Immagina di aver appena costruito un assistente robotico super intelligente. Hai dato al robot un cervello (un modello di IA massiccio) e gli hai detto: "Vai a riparare il mio computer!". Ma il cervello da solo non basta. Il robot ha bisogno di un corpo, di un sistema nervoso e di un insieme di istruzioni su come muovere le dita, impugnare un cacciavite e capire quando ha finito. Nel mondo dell'IA, questo "corpo e sistema nervoso" è chiamato harness (imbracatura). È lo strato software che dice all'IA quando parlare, quando usare uno strumento e come ricordare ciò che ha appena fatto.

Ora, immagina di voler aggiornare quel robot. Magari vuoi che sia più prudente prima di eliminare un file, o forse vuoi che controlli il suo lavoro tre volte invece di una. Nei vecchi tempi, un programmatore umano avrebbe dovuto scavare attraverso migliaia di righe di codice, cercando di capire esattamente dove fosse nascosta quella regola del "controlla il tuo lavoro" nel sistema nervoso del robot. È come cercare di trovare un nervo specifico in un enorme gomitolo di lana aggrovigliato. Il codice è spesso distribuito in molti file diversi, mescolato con altra logica, ed è difficile da tracciare. Se ne perdi anche solo uno, il tuo robot potrebbe ancora eliminare file per errore. Questo articolo affronta l'esasperante problema di trovare quei punti nascosti per poter aggiornare in sicurezza i nostri assistenti IA.

I ricercatori dietro questo studio, guidati da Ruhan Wang e colleghi, hanno capito che il collo di bottiglia principale non è insegnare all'IA come apportare modifiche, ma aiutare gli esseri umani (o altri agenti IA) a capire dove farle. Chiamano questo problema localizzazione del comportamento (behavior localization). Per risolverlo, hanno inventato qualcosa chiamato Harness Handbook (Il Manuale dell'Imbracatura).

Pensa all'Harness Handbook non come a un elenco di file, ma come a un manuale d'uso per il comportamento del robot. Invece di organizzare le informazioni per "File A, File B, File C" (che è il modo in cui il codice viene solitamente memorizzato), l'Harness Handbook le organizza in base a "Cosa fa effettivamente il robot". È come avere una guida che dice: "Se vuoi cambiare il modo in cui il robot gestisce un segnale di 'Compito Completato', ecco i tre punti specifici nel suo cervello dove quel segnale viene elaborato, ed ecco esattamente come comunicano tra loro".

Il team ha costruito un sistema che crea automaticamente questo Manuale leggendo il codice del robot e usando un'IA intelligente per mappare le connessioni. Chiamano il metodo di utilizzare questa mappa Divulgazione Progressiva Guidata dal Comportamento (Behavior-Guided Progressive Disclosure). Immagina di cercare di riparare un orologio complesso. Invezione di fissare un mucchio di 500 ingranaggi e molle, apri un manuale che prima ti mostra la sezione "Indicazione dell'ora", poi zooma sull'ingranaggio della "Lancetta delle ore" e infine evidenzia la vite esatta che devi girare. L'Harness Handbook fa questo per il codice dell'IA: parte da una panoramica di alto livello di ciò che il sistema fa, poi guida l'utente verso le righe di codice specifiche che devono essere modificate.

I ricercatori hanno testato questa idea su due sistemi reali di IA (chiamati Terminus-2 e Codex). Hanno chiesto ad agenti di codifica di apportare modifiche basate su richieste semplici come: "Fai in modo che il robot chieda conferma tre volte prima di valutare un compito". Hanno confrontato due gruppi: un gruppo doveva trovare il codice nel modo tradizionale (cercando tra i file) e l'altro utilizzava l'Harness Handbook.

I risultati sono stati chiari. Il gruppo che utilizzava l'Harness Handbook è stato molto più bravo a trovare i punti giusti da modificare. Ha commesso meno errori, non ha cambiato accidentalmente cose che non doveva toccare e ha fatto tutto utilizzando meno potenza di calcolo (meno "token", che è come la valuta con cui l'IA spende per pensare). L'Harness Handbook è stato particolarmente utile quando il codice era disordinato, distribuito su molti file o nascosto in parti del sistema che vengono eseguite raramente. Infatti, gli agenti che usavano l'Harness Handbook erano così bravi a trovare il codice giusto che un modello di IA "più debole" poteva performare quasi quanto uno "più forte" semplicemente avendo a disposizione la mappa.

L'articolo suggerisce che man mano che i sistemi di IA diventano più complessi, non possiamo limitarci a contare su cervelli più intelligenti; abbiamo bisogno di mappe migliori. L'Harness Handbook dimostra che se organizziamo il codice attorno a ciò che il sistema fa anziché a dove si trovano i file, possiamo rendere l'evoluzione di questi potenti agenti molto più sicura, veloce e affidabile. Trasforma il compito caotico di sbrogliare un enorme gomitolo di lana in un semplice viaggio guidato attraverso una biblioteca ben illuminata.

Riepilogo Tecnico: Harness Handbook

Problema

L'evoluzione dei moderni sistemi di agenti AI è sempre più limitata dalla difficoltà della localizzazione del comportamento (behavior localization) all'interno di harness di produzione su larga scala. Un harness è lo strato software che costruisce i prompt, gestisce lo stato, invoca gli strumenti e coordina l'esecuzione, traducendo efficacemento le capacità dei modelli di base in comportamento di sistema. Quando i requisiti cambiano, gli sviluppatori o gli agenti di codifica devono modificare questi harness. Tuttavia, identificare tutti i punti del codice che implementano una specifica richiesta comportamentale è notoriamente difficile perché:

Complessità Strutturale: I comportamenti sono spesso distribuiti tra file non adiacenti, funzioni, stadi di esecuzione e transizioni di stato condiviso.
Disallineamento della Rappresentazione: Le richieste di modifica descrivono cosa il sistema debba fare (comportamento), mentre i repository sono organizzati in base a come è strutturato il codice (file, moduli, funzioni).
Limitazioni degli Strumenti Esistenti: Gli approcci attuali (ricerca nel codice, indicizzazione del repository, elaborazione a lungo contesto) organizzano le informazioni attorno agli artefatti di implementazione. Aiutano a individuare singoli frammenti di codice, ma non riescono a mappare esplicitamente come parti sparse lavorino insieme per produrre un determinato comportamento, lasciando che sia l'agente o lo sviluppatore a dover inferire tali connessioni manualmente.

Questo divario costringe gli sviluppatori a costruire modelli mentali del sistema e gli agenti a esplorare iterativamente i repository, spesso perdendo di vista percorsi di codice sparsi o raramente eseguiti.

Metodologia

Il paper introduce Harness Handbook, una rappresentazione centrata sul comportamento sintetizzata automaticamente da un codebase di un harness, e la Behavior-Guided Progressive Disclosure (BGPD), un workflow per utilizzare tale rappresentazione.

1. Rappresentazione Harness Handbook

L'Handbook riorganizza la conoscenza dell'implementazione attorno al comportamento a runtime piuttosto che alla struttura dei file. Consiste in due viste complementari:

Albero Documentale ( $D$ ): Una gerarchia a tre livelli (L1–L3) che progredisce dalle panoramiche di alto livello del sistema fino alle unità dettagliate basate sul codice sorgente.
- L1 (Panoramica di Sistema): Architettura, modello di esecuzione, stadi principali e flusso globale dei dati.
- L2 (Panoramica del Componente): Responsabilità, input/output, dipendenze e stato locale per specifici stadi di esecuzione.
- L3 (Approfondimento dell'Unità): Voci di implementazione basate sulla sorgente (funzioni o file) collegate a specifici punti del codice.
Vista del Registro di Stato ( $Z$ ): Una vista cross-stage che traccia le relazioni di stato che attraversano i confini degli stadi, garantendo che i comportamenti dipendenti dallo stato condiviso siano catturati anche se strutturalmente distanti.

La rappresentazione aderisce a due regole:

Progressive Disclosure (Rivelazione Progressiva): I lettori si muovono da L1 a L3 solo quando un compito richiede maggiore dettaglio.
Allineamento Comportamento–Implementazione: Ogni localizzatore L3 attivo deve risolvere un punto nel repository sorgente corrente. Se un localizzatore non può essere rivalidato, viene congelato per evitare allucinazioni.

2. Pipeline di Costruzione

L'Handbook viene costruito automaticamente da un repository ( $R$ ) attraverso tre fasi:

Fase I: Estrazione di Fatti Statici: Il parsing deterministico estrae funzioni, grafi di chiamata e accessi allo stato. Le chiamate non risolte vengono registrate invece di essere ipotizzate.
Fase II: Organizzazione Comportamentale: Le unità sorgente vengono mappate su uno scheletro di esecuzione ( $S$ $S$ ). La pipeline supporta due modalità foglia:
- Funzione-come-foglia: Parte da uno scheletro iniziale e assegna funzioni (o regioni contigue) agli stadi.
- File-come-foglia: Inferisce lo scheletro degli stadi dalle sintesi dei file e organizza i file di conseguenza.
Fase III: Sintesi Gerarchica: Converte l'organizzazione nell'albero documentale L1–L3 e nella vista del registro di stato, validando tutti i localizzatori rispetto alla sorgente.

3. Workflow di Modifica (BGPD)

Il workflow per modificare un harness utilizzando l'Handbook prevede quattro passaggi:

Localizzazione: L'agente utilizza la BGPD per navigare l'Handbook da una granularità grossolana (L1/L2) a una fine (L3). Identifica gli stadi rilevanti e i registri di stato, espande l'insieme dei candidati tramite i grafi di chiamata e verifica poi questi candidati rispetto al corrente repository sorgente per produrre evidenza verificata ($bEq$).
Pianificazione: Un pianificatore converte $bEq$ in un piano di modifica ( $P$ ) e in dichiarazioni di azione ( $\Gamma$ ).
Esecuzione: Un esecutore applica il piano al repository.
Resincronizzazione: Qualsiasi diff non vuoto innesca una resincronizzazione automatica dell'Handbook. Il sistema aggiorna solo le parti interessate (usando fingerprint o hash di contenuto) invece di ricostruire l'intero Handbook, garantendo che la rappresentazione rimanga coerente con l'evolving codebase.

Contributi Chiave

Definizione di Localizzazione del Comportamento: Il paper definisce formalmente la localizzazione del comportamento come il passaggio preliminare necessario per trovare tutte le posizioni del codice che implementano una richiesta comportamentale prima che una modifica possa essere pianificata.
Harness Handbook: Una nuova rappresentazione generata automaticamente che collega le descrizioni comportamentali direttamente alle implementazioni distribuite della sorgente, organizzata per "cosa fa l'harness" anziché per struttura dei file.
Workflow BGPD: Un metodo per guidare gli agenti di codifica dalle descrizioni comportamentali di alto livello ai dettagli di implementazione rilevanti attraverso gli stadi, verificando i candidati rispetto alla sorgente live.
Validazione Empirica: Valutazione su due harness open-source (Terminus-2 e Codex) che dimostra come la pianificazione assistita dall'Handbook migliori l'accuratezza della localizzazione e la qualità del piano di modifica, riducendo al contempo l'uso di token.

Risultati Sperimentali

Gli autori hanno valutato l'approccio su 60 richieste di modifica (30 per ogni harness) di tre tipi: Query (modifica di un comportamento esistente), Cross-file (aggiunta di capacità che spaziano tra i moduli) e Search-Hostile (implementazioni nascoste in percorsi difficili da trovare).

Qualità del Piano e Costo: La pianificazione assistita dall'Handbook ha ottenuto tassi di vittoria significativamente più alti nella qualità del piano (ad esempio, +18,9% su Terminus-2) rispetto a un baseline che esplora direttamente il repository. Fondamentalmente, questo miglioramento è stato ottenuto con meno token del pianificatore (riduzioni del 12,7% e dell'8,6% su Codex e Terminus-2, rispettivamente), indicando una maggiore efficienza piuttosto che un semplice aumento del budget.
Accuratezza della Localizzazione: Un pianificatore più debole (DeepSeek-V4-Pro) assistito dall'Handbook ha eguagliato la localizzazione dei siti di implementazione di modelli sostanzialmente più forti (Opus 4.8, GPT-5.5). Gli score F1 per la localizzazione a livello di file e di simbolo sono migliorati di 5,0 - 18,8 punti in tutti i confronti. La metrica "Wrong" (zero sovrapposizione con il riferimento) è diminuita significativamente, indicando meno fallimenti totali.
Robustezza: I guadagni sono persistiti in tutti i tipi di richiesta (Query, Cross-file, Search-Hostile) e livelli di difficoltà (Easy, Medium, Hard). I miglioramenti più significativi sono stati osservati in modifiche che coinvolgono siti di implementazione sparsi e interazioni tra moduli.

Significato e Rivendicazioni

Il paper sostiene che l'evoluzione di sistemi agentici complessi dipende non solo dal generare modifiche, ma anche dal determinare dove tali modifiche debbano essere effettuate. Rendendo esplicito il collegamento tra comportamento e implementazione, l'Harness Handbook affronta il collo di bottiglia centrale della localizzazione del comportamento.

Gli autori pongono questo lavoro come un passo verso l'auto-evoluzione dell'harness. Suggeriscono che una rappresentazione del repository centrata sul comportamento, che rimanga sincronizzata con il codice, possa supportare usi più ampi come l'audit del comportamento e l'analisi dell'impatto delle regressioni. L'obiettivo finale è consentire agli agenti di chiudere autonomamente il ciclo di localizzazione, pianificazione, esecuzione e resincronizzazione, portando gli harness degli agenti verso l'auto-miglioramento senza richiedere budget di token di pianificazione più elevati.