TRAJEVAL: Decomposing Code Agent Trajectories for Fine-Grained Diagnosis

Il paper introduce TRAJEVAL, un framework diagnostico che scompone le traiettorie degli agenti di codice in tre fasi interpretabili (ricerca, lettura e modifica) per identificare le cause specifiche dei fallimenti e migliorare le prestazioni dei modelli tramite feedback in tempo reale, superando i limiti delle metriche di valutazione binaria tradizionali.

L'essenziale

🕵️‍♂️ Il Problema: "L'Agente ha risolto il problema, ma come?"

Immagina di avere un bravo assistente virtuale (un "agente di codice") che deve riparare un guasto in una casa complessa (un software).
Fino a oggi, per sapere se l'assistente era bravo, guardavamo solo il risultato finale:

• ✅ La casa è riparata? (Pass@1: Sì/No).
• ❌ La casa è ancora rotta? (Pass@1: No).

Il problema è che se l'assistente fallisce, non sappiamo dove ha sbagliato. Ha cercato la stanza sbagliata? Ha letto il manuale ma non l'ha capito? O ha trovato il pezzo rotto ma ha usato il martello invece del cacciavite?
È come dire a un medico: "Il paziente è guarito" o "Il paziente è morto", senza sapere quale medicina ha funzionato o quale diagnosi era errata.

🛠️ La Soluzione: TRAJEVAL (Il "Raggiro" per vedere dentro il processo)

Gli autori hanno creato TRAJEVAL, un sistema che non guarda solo il risultato, ma analizza il viaggio (la "traiettoria") che l'agente ha fatto per arrivare alla soluzione.

Hanno diviso il lavoro dell'agente in tre fasi, come se fosse un investigatore che risolve un caso:

1. 🔍 Fase 1: Cerca (Search)
   • L'analogia: L'agente deve trovare la stanza giusta nella casa.
   • Cosa misura: È riuscito a trovare il file corretto? O ha perso tempo a girare per tutto il corridoio?
2. 📖 Fase 2: Leggi (Read)
   • L'analogia: Una volta dentro la stanza, l'agente deve capire quale oggetto è rotto.
   • Cosa misura: Ha letto le istruzioni giuste? O ha guardato solo la polvere sul pavimento?
3. 🔧 Fase 3: Modifica (Edit)
   • L'analogia: L'agente deve riparare l'oggetto.
   • Cosa misura: Ha colpito il chiodo giusto? O ha rotto qualcos'altro mentre cercava di aggiustare?

Per ogni fase, TRAJEVAL calcola due numeri magici:

• Precisione (Efficienza): Quanto tempo ha sprecato? (Se ha letto 100 pagine per trovarne 1 utile, la precisione è bassa).
• Ritorno (Recall): Ha trovato tutto ciò che serviva? (Se ha trovato 100 pagine ma ne mancavano 2 fondamentali, il ritorno è basso).

🔍 Cosa hanno scoperto? (Le sorprese)

Analizzando quasi 17.000 tentativi di agenti diversi, hanno scoperto cose affascinanti:

1. Tutti sono un po' "spendaccioni":
   Gli agenti tendono a esplorare 22 volte più codice di quanto sia necessario. È come se per trovare un ago in un pagliaio, decidessero di bruciare tutto il pagliaio per essere sicuri. Funziona, ma costa molto tempo e soldi.
2. Non tutti falliscono allo stesso modo:
   • GPT-5: È bravissimo a trovare la stanza giusta e a leggere il manuale, ma spesso sbaglia il colpo finale. Capisce il problema, ma non sa dove applicare la soluzione.
   • Qwen-32B: Fa fatica anche solo a trovare la stanza giusta. Si perde all'inizio e non riesce mai a iniziare il lavoro.
3. Il segreto del successo non è la velocità:
   Chi risolve il problema non è necessariamente quello che legge meno codice. Chi risolve il problema è quello che trova tutto il codice necessario (alta "Recall"), anche se poi ne legge un po' di troppo.

🚀 L'uso pratico: Dare consigli in tempo reale

La parte più potente di TRAJEVAL non è solo diagnosticare, ma correggere mentre si lavora.

Immagina di guidare un'auto con un navigatore che ti dice: "Ehi, stai guardando la strada giusta! Continua così!" oppure "Attenzione, stai guardando un vicolo cieco, torna indietro!".
Gli autori hanno testato questo sistema: quando l'agente trovava il codice giusto, il sistema gli dava un "pollice in su" digitale.
Risultato?

• Gli agenti sono diventati più bravi (hanno risolto più problemi).
• Hanno speso meno soldi e tempo (hanno smesso di girare a vuoto).

🎯 In sintesi

TRAJEVAL trasforma la valutazione degli agenti di codice da un semplice "Voto Passa/Non Passa" a una diagnosi medica dettagliata.
Invece di dire "L'agente è scarso", ora possiamo dire: "L'agente è bravo a cercare, ma deve imparare a leggere meglio le istruzioni".

Questo permette di migliorare gli assistenti AI in modo intelligente, rendendoli non solo più efficaci, ma anche più economici e veloci, proprio come un meccanico esperto che sa esattamente quale pezzo del motore sta facendo rumore.

Sommario tecnico

1. Il Problema

Gli agenti di codice basati su Large Language Models (LLM) sono sempre più capaci di risolvere autonomamente problemi su GitHub, generando patch che superano i test unitari. Tuttavia, le attuali metodologie di valutazione si basano quasi esclusivamente su metriche outcome-based (basate sul risultato finale), come il Pass@k.
Queste metriche riducono l'intera esecuzione di un agente a un singolo risultato binario (successo/fallimento), offrendo zero visibilità su:

• Dove l'agente ha fallito (es. non ha trovato il file giusto, non ha capito la funzione, o ha modificato il codice nel posto sbagliato).
• Perché un agente ha fallito mentre un altro è riuscito.
• Quali inefficienze comportamentali siano presenti anche negli agenti che hanno successo.

Questa mancanza di trasparenza impedisce un miglioramento mirato degli agenti e rende difficile diagnosticare i colli di bottiglia specifici.

2. Metodologia: Il Framework TRAJEVAL

Gli autori introducono TRAJEVAL, un framework diagnostico che scompone la traiettoria di esecuzione di un agente in tre fasi interpretabili, confrontandole con una "patch di riferimento" (golden patch) che rappresenta la soluzione corretta.

Le tre fasi sono:

1. Search (Ricerca): Localizzazione a livello di file. L'agente riesce a trovare i file corretti nel repository?
2. Read (Lettura): Comprensione a livello di funzione. Una volta aperto il file, l'agente esamina le funzioni rilevanti?
3. Edit (Modifica): Targeting delle modifiche. L'agente applica le modifiche alle funzioni corrette?

Per ciascuna fase, il framework calcola due metriche standard di Information Retrieval:

• Precision: Efficienza (quanto dell'esplorazione dell'agente è stata necessaria?).
• Recall: Efficacia (quanto del contesto necessario è stato identificato con successo?).

Definizione del "Golden Context":
Il contesto aureo è definito gerarchicamente:

• Tier 0 (Core): File e funzioni modificati esplicitamente nella patch di riferimento.
• Tier 1 (Extended): Tier 0 più le dipendenze strutturali a un passo (import, test, classi genitore) estratte tramite analisi statica.
  Le metriche di Recall sono calcolate rispetto al Tier 0 (per misurare la scoperta essenziale), mentre le metriche di Precision beneficiano del Tier 1 per distinguere l'esplorazione ragionevole dal rumore.

L'estrazione delle caratteristiche è agnostica rispetto all'architettura dell'agente e utilizza parser AST (tree-sitter) e regex per mappare le azioni dell'agente (es. view, edit, bash) ai file e funzioni toccati.

3. Contributi Chiave

1. Framework Diagnostico: Introduzione di TRAJEVAL, che trasforma i log di esecuzione non strutturati in segnali quantitativi specifici per fase (Precision/Recall per Search, Read, Edit).
2. Analisi su Grande Scala: Valutazione di 16.758 traiettorie attraverso 3 architetture di agenti (SWE-Agent, OpenHands, LiveSWE-Agent) e 7 modelli linguistici (da 8B a 480B parametri) su due benchmark (SWE-bench Verified e PolyBench).
3. Scoperta di Modelli di Fallimento Distintivi: Dimostrazione che diversi modelli falliscono in modi diversi (es. GPT-5 trova il codice ma sbaglia il target di modifica; Qwen-32B fallisce nella scoperta dei file).
4. Predizione e Azionabilità: Validazione che le caratteristiche della traiettoria possono prevedere il successo (Pass@1) con alta accuratezza e che il feedback basato su questi segnali può migliorare le prestazioni in tempo reale.

4. Risultati Principali

A. Predizione del Successo (Pass@1)

Le caratteristiche derivate dalla traiettoria (6 metriche totali) sono altamente predittive del successo del task.

• Un semplice modello di regressione logistica predice il Pass@1 con un Mean Absolute Error (MAE) tra 0.87% e 2.1%.
• La correlazione di ranking (Spearman's ρ) rimane perfetta o quasi perfetta (≥ 0.886) anche sotto spostamenti di distribuzione (repository o linguaggio di programmazione non visti durante l'addestramento).

B. Comportamenti Universali e Inefficienze

• Sovra-esplorazione Universale: Tutti gli agenti esaminano un numero di funzioni 22 volte superiore a quello necessario. La Precision è costantemente bassa (4-5% nella fase di lettura), indicando che gli agenti sacrificano l'efficienza per la copertura.
• Il Recall è il fattore determinante: A differenza della precisione, il Recall (specialmente nella fase di Edit) correla fortemente con il completamento del task. Un agente che esplora tutto ma modifica la funzione giusta ha successo; un agente efficiente che salta la funzione giusta fallisce.

C. Diagnosi dei Modelli

L'analisi rivela "modi di fallimento" specifici per modello:

• GPT-5: Ottima capacità di ricerca e lettura (Recall alto), ma fallisce spesso nel targeting delle modifiche (Edit Recall basso).
• Qwen-32B: Fallisce completamente nella fase di scoperta dei file (Search Recall basso), non riuscendo a localizzare i file rilevanti.
• Qwen-8B: Mostra difficoltà nella comprensione semantica (Read Recall basso) anche quando i file sono trovati.

D. Intervento in Tempo Reale (Actionable Feedback)

Gli autori hanno implementato un meccanismo di feedback in tempo reale: quando un agente tocca un file o una funzione del "golden context", riceve un segnale di conferma ("✓Stai esaminando codice rilevante").

• Risultati: Questo feedback ha migliorato il Pass@1 di 2.2–4.6 punti percentuali per due modelli SOTA.
• Efficienza: Ha ridotto l'uso di token fino al 29% e i costi fino al 31%, guidando gli agenti verso esplorazioni più produttive e riducendo il tempo di convergenza.

5. Significato e Impatto

Il lavoro di TRAJEVAL rappresenta un cambio di paradigma fondamentale nella valutazione degli agenti di codice:

1. Da Risultato a Meccanismo: Sposta il focus dal "cosa" è successo (successo/fallimento) al "come" e "perché" è successo, permettendo una diagnosi granulare.
2. Ottimizzazione Mirata: Permette agli sviluppatori di identificare colli di bottiglia specifici (es. "il modello non sa cercare i file" vs "il modello non sa modificare il codice") e applicare interventi specifici.
3. Efficienza Operativa: Dimostra che la diagnosi basata sulla traiettoria non è solo descrittiva, ma abilita interventi attivi che migliorano sia l'accuratezza che l'efficienza economica degli agenti.

In sintesi, TRAJEVAL trasforma l'analisi degli agenti da una "scatola nera" a un processo trasparente e ottimizzabile, fornendo gli strumenti necessari per comprendere e migliorare il comportamento degli agenti di codice autonomi.