💬 NLP

Agent-Diff: Benchmarking LLM Agents on Enterprise API Tasks via Code Execution with State-Diff-Based Evaluation

Il paper presenta Agent-Diff, un nuovo framework di benchmarking che valuta le prestazioni degli agenti LLM su compiti reali con API aziendali attraverso l'esecuzione di codice in un ambiente sandboxizzato, utilizzando un innovativo contratto di "state-diff" per misurare il successo in base ai cambiamenti effettivi dello stato dell'ambiente piuttosto che alla corrispondenza dei parametri.

Autori originali: Hubert M. Pysklo, Artem Zhuravel, Patrick D. Watson

Pubblicato 2026-03-26

📖 5 min di lettura🧠 Approfondimento

CC BY 4.0

Autori originali: Hubert M. Pysklo, Artem Zhuravel, Patrick D. Watson

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

🕵️‍♂️ Agent-Diff: Il "Gioco di Ruolo" per gli Agenti AI

Immagina di voler testare quanto sono bravi i nuovi assistenti virtuali (chiamati Agenti AI) a gestire compiti reali, come organizzare una riunione, spostare file o inviare messaggi. Il problema è: come fai a sapere se hanno davvero fatto il lavoro o se hanno solo "finto" di farlo?

Fino a poco tempo fa, i test per queste intelligenze artificiali erano come due estremi opposti:

La simulazione di plastica: Si usava un ambiente finto, dove tutto era perfetto e prevedibile. Era come guidare un'auto in un videogioco: sicuro, ma non ti dice se sai davvero guidare nel traffico vero.
Il caos della strada vera: Si usavano servizi reali (come Slack o Google Calendar). Era realistico, ma rischioso: se l'AI sbagliava, poteva cancellare file veri o inviare email a persone sbagliate. Inoltre, ogni volta che si faceva il test, lo stato del mondo era diverso (chiunque poteva aver modificato qualcosa), rendendo i risultati non confrontabili.

Agent-Diff è la soluzione creativa che unisce il meglio dei due mondi. È come costruire un parco giochi perfetto e sicuro, ma con le stesse regole, gli stessi ostacoli e gli stessi strumenti del mondo reale.

🏗️ Come funziona? I tre pilastri magici

1. La "Copia Perfetta" (Il Sandbox)

Immagina di avere un'azienda reale con migliaia di dipendenti. Agent-Diff crea una copia esatta di quell'azienda, ma isolata in una bolla di vetro.

Quando l'AI scrive codice per dire "Crea un nuovo file", il comando non va al vero server di Box o Slack, ma a una copia identica ospitata in un contenitore digitale.
È come se l'AI pensasse di essere in un ufficio reale, ma in realtà sta giocando in una stanza dove nessuno può farsi male e dove il "gioco" può essere resettato all'istante.

2. Il "Contratto di Differenza" (State-Diff)

Questa è l'idea più geniale. Invece di guardare come l'AI ha lavorato (se ha cliccato sul tasto giusto, se ha scritto bene il codice), Agent-Diff guarda solo il risultato finale.

L'analogia della stanza: Immagina di dare a un maggiordomo (l'AI) l'ordine: "Sposta la sedia dalla finestra alla porta e metti un vaso di fiori sul tavolo".
- I vecchi metodi guardavano se il maggiordomo aveva usato la mano destra o sinistra, o se aveva camminato in modo elegante.
- Agent-Diff fa una foto della stanza prima e una dopo.
- Calcola la differenza (il "diff"): La sedia è alla porta? Sì. C'è un vaso sul tavolo? Sì. C'è qualcosa di rotto o spostato che non doveva esserlo? No.
- Se la differenza tra la foto "prima" e la foto "dopo" corrisponde esattamente a quello che era stato chiesto, l'AI passa il test. Se l'AI ha rotto una finestra mentre spostava la sedia, il test fallisce, anche se ha spostato la sedia correttamente.

3. Il "Libro delle Regole" (API Documentation)

Il paper testa anche quanto gli AI hanno bisogno di leggere le istruzioni.

Scenario A: L'AI deve indovinare come funziona il servizio (come un bambino che prova a usare un telecomando senza istruzioni).
Scenario B: L'AI ha il manuale completo sottomano.
Risultato: Gli AI più bravi migliorano molto quando hanno il manuale, specialmente per compiti nuovi. Quelli meno bravi spesso si confondono anche con il manuale, o peggio, inventano cose (allucinazioni) pensando di sapere già tutto.

🧪 Cosa hanno scoperto? (I risultati)

Gli autori hanno messo alla prova 9 diversi modelli di AI su 224 compiti reali (dalla gestione di file su Box, ai messaggi su Slack, fino ai calendari). Ecco le scoperte principali:

Non tutti sono uguali: C'è una grande differenza tra i "campioni" e i "novizi". I modelli migliori (come DeepSeek-v3.2 e Devstral) hanno superato l'88% dei compiti, mentre quelli più deboli sono rimasti sotto il 40%.
Il costo conta: Alcuni modelli costano pochissimo e sono velocissimi, altri costano una fortuna e fanno più errori. C'è un modello che è 33 volte più efficiente in termini di costo/beneficio rispetto a un altro!
L'importanza di leggere le istruzioni: Dare all'AI le istruzioni tecniche (la documentazione) aiuta moltissimo a completare i compiti semplici, ma non risolve magicamente i problemi complessi. Se l'AI non sa ragionare, anche con il manuale in mano sbaglia.
Il segreto dei bravi: Cosa fanno i modelli vincenti quando sbagliano? Non riprovano la stessa cosa all'infinito (come farebbero i modelli deboli). Invece, si fermano, leggono l'errore, cercano informazioni nuove e cambiano strategia. È la differenza tra un bambino che piange perché non apre la scatola e un adulto che cerca il cacciavite giusto.

🚀 In sintesi

Agent-Diff è come un campo di addestramento militare digitale per le intelligenze artificiali. Non si limita a chiedere "Hai finito?", ma controlla se il campo di battaglia è esattamente come doveva essere alla fine della missione, senza danni collaterali.

Questo ci dice che per avere veri assistenti AI nel mondo reale, non basta che siano veloci o che parlino bene: devono essere capaci di pianificare, adattarsi agli errori e garantire che il risultato finale sia corretto, proprio come un umano esperto.

1. Il Problema

L'articolo affronta la sfida di valutare le prestazioni degli agenti basati su Large Language Models (LLM) in scenari reali di produttività aziendale. Esistono due approcci principali nei benchmark esistenti, entrambi con limiti significativi:

Ambienti sandboxizzati (mock/sintetici): Offrono riproducibilità e controllo, ma spesso non catturano la complessità e il comportamento reale delle API aziendali, portando a valutazioni che non si traducono bene nel mondo reale.
Servizi live (reali): Offrono alta validità ecologica, ma introducono instabilità temporale, difficoltà nel recuperare la "verità fondamentale" (ground truth) e problemi di riproducibilità a causa dello stato dinamico dei servizi.

Inoltre, molti benchmark attuali valutano l'agente basandosi sulla corrispondenza delle tracce di esecuzione (quali tool sono stati chiamati) o su valutazioni soggettive (LLM-as-a-judge), invece di verificare se lo stato finale del sistema corrisponda effettivamente all'obiettivo desiderato. Questo rende difficile distinguere tra un agente che ha raggiunto il risultato corretto e uno che ha semplicemente seguito un percorso simile ma fallito.

2. Metodologia: Agent-Diff

Gli autori propongono Agent-Diff, un framework di benchmarking che combina i vantaggi degli ambienti sandbox con l'interazione su interfacce API reali. La metodologia si basa su tre pilastri fondamentali:

A. Architettura Sandbox e Replica delle API

Repliche Containerizzate: Invece di chiamare le API reali (es. Slack, Box, Linear, Google Calendar) direttamente, il sistema utilizza repliche containerizzate di questi servizi. Queste repliche sono costruite basandosi sulle specifiche pubbliche delle API (OpenAPI, GraphQL) e sono collegate a database PostgreSQL isolati.
Isolamento Deterministico: Ogni esecuzione del benchmark avviene in un ambiente isolato con uno stato iniziale identico (seedato da template predefiniti). Questo garantisce che tutti i modelli vengano testati contro le stesse condizioni iniziali, eliminando l'instabilità temporale.
Interazione via Codice: Gli agenti non chiamano tool strutturati (come JSON schema), ma scrivono ed eseguono codice (principalmente Bash/curl) per interagire direttamente con le API, simulando un uso reale e scalabile.

B. Valutazione basata su State-Diff (Contratto di Stato)

Questa è l'innovazione centrale del paper. Invece di confrontare la sequenza di azioni dell'agente con una traccia ideale, il sistema valuta il risultato.

Snapshot dello Stato: Prima e dopo l'esecuzione del task, viene catturato lo stato completo del database (snapshot delle tabelle delle entità).
Calcolo della Diff: Viene calcolato la differenza tra lo stato finale e quello iniziale ( $\Delta S = S_{final} - S_{initial}$ ). Questa differenza include entità inserite, cancellate o modificate.
Contratto di Verifica: Ogni task è definito da un insieme di asserzioni dichiarative che specificano le modifiche attese nello stato (es. "un file deve essere stato creato", "un evento deve essere stato aggiornato").
Invariante del Mondo Chiuso: Il sistema verifica che qualsiasi cambiamento nello stato sia spiegabile dalle asserzioni del task. Se l'agente modifica o cancella risorse non pertinenti (effetti collaterali indesiderati), il task fallisce. Questo previene l'inganno tramite modifiche parziali o accidentali.

C. Generazione dei Task

Il benchmark comprende 224 task distribuiti su 4 servizi enterprise. I task sono generati proceduralmente e curati manualmente per variare lungo cinque dimensioni:

Orizzonte temporale ( $n^*$ ): Numero minimo di chiamate API necessarie (da 1 a 24).
Profilo operativo: Combinazione di operazioni CRUD (Cerca, Crea, Leggi, Aggiorna, Cancella).
Ambito delle entità: Task su singola entità vs. task multi-entità (che richiedono coordinamento tra tabelle diverse).
Disponibilità delle informazioni: Gli ID necessari sono forniti esplicitamente nel prompt o devono essere scoperti dall'agente tramite query API (informazioni implicite).
Ambiguità: Grado in cui il prompt è sottodeterminato (bassa, media, alta ambiguità).

3. Risultati Sperimentali

Il framework è stato utilizzato per valutare 9 modelli LLM (tra cui DeepSeek-v3.2, Devstral-2512, Qwen3-VL, Grok-4.1, Claude-Haiku, Llama-4-Scout, ecc.) in tre condizioni: senza documentazione, con documentazione rilevante e con tutta la documentazione.

Prestazioni Generali: I modelli mostrano un ampio spettro di prestazioni. DeepSeek-v3.2 e Devstral-2512 si posizionano al vertice con punteggi globali di circa 88.1 e 86.0 rispettivamente (su una scala di successo ponderata). I modelli più piccoli o meno ottimizzati (es. Llama-4-Scout, Claude-Haiku-4.5) scendono sotto il 50%.
Effetto della Documentazione:
- Fornire la documentazione API specifica migliora significativamente il tasso di passaggio (pass rate) (+7.0 punti percentuali), aiutando gli agenti a completare task semplici.
- Tuttavia, il punteggio complessivo ponderato non mostra un miglioramento statisticamente significativo (+2.4 punti, non significativo). Questo suggerisce che la documentazione aiuta a evitare errori di base, ma non risolve necessariamente le difficoltà nei task complessi multi-step.
- L'effetto è più marcato per le API recenti (es. Box Hub API, introdotta dopo il training cut-off dei modelli), dove la documentazione è essenziale per scoprire endpoint sconosciuti.
Analisi degli Errori e Recupero:
- Gli errori più comuni sono fallimenti nel ragionamento (53.6%) e errori nei parametri (43.3%).
- I modelli ad alte prestazioni tendono a utilizzare strategie di recupero proattive e adattive: break_into_steps (scomporre il task), lookup_correct_value (cercare i valori corretti) e verify_prerequisites (verificare le precondizioni).
- I modelli con prestazioni inferiori tendono a fallire ripetendo la stessa azione errata (retry_same), una strategia che si è rivelata universalmente dannosa.
Efficienza dei Costi: Grok-4.1-Fast ha mostrato la migliore efficienza costo/prestazioni, superando modelli molto più costosi di 5-8 volte in termini di punteggio per dollaro.

4. Contributi Chiave

Framework Ibrido: Un approccio che unisce la validità ecologica delle API reali con la riproducibilità rigorosa degli ambienti sandboxizzati.
Valutazione State-Diff: Un metodo di valutazione oggettivo e deterministico che verifica il risultato (cambiamento di stato) anziché il processo (traccia di chiamate), permettendo di rilevare effetti collaterali indesiderati.
Dataset Completo: Un benchmark di 224 task su 4 servizi enterprise reali, con annotazioni dettagliate su difficoltà, ambiguità e scope.
Analisi Strutturale: Una profonda analisi delle strategie di recupero degli errori, dimostrando che la capacità di pianificazione e adattamento (non solo la conoscenza delle API) è il fattore discriminante tra i modelli top-tier e quelli inferiori.

5. Significato e Implicazioni

Il lavoro di Agent-Diff segna un passo avanti significativo nella valutazione degli agenti AI per l'automazione aziendale. Dimostra che:

La semplice capacità di chiamare tool non è sufficiente; gli agenti devono essere capaci di pianificare sequenze complesse, gestire lo stato e recuperare dagli errori in modo adattivo.
La documentazione API è cruciale per task che coinvolgono funzionalità nuove o poco conosciute, ma non risolve magicamente le carenze nel ragionamento logico.
L'approccio "State-Diff" offre un nuovo standard per la valutazione, spostando il focus dalla correttezza sintattica delle chiamate alla correttezza semantica dell'azione compiuta sul sistema.

Il codice e i dati sono stati resi disponibili pubblicamente, permettendo alla comunità di ricerca di riprodurre i risultati e sviluppare agenti più robusti per l'uso in ambienti enterprise reali.