MAC-SQL è arrivato a dicembre 2023 come la risposta più esplicitamente incentrata sugli agenti al problema text-to-SQL: invece di un singolo prompt che genera una query, tre agenti specializzati collaborano per selezionare un sotto-schema rilevante, scomporre la domanda e riparare l'SQL dopo l'esecuzione. Lo leggo perché i due articoli precedenti riguardavano BIRD (il benchmark che MAC-SQL aveva scalato al momento della sottomissione) e DIN-SQL (la baseline di scomposizione che MAC-SQL estende), e la domanda naturale è se un wrapper multi-agente offra qualcosa di concreto oltre queste basi.
L'articolo
"MAC-SQL: A Multi-Agent Collaborative Framework for Text-to-SQL" (Wang et al., COLING 2025) affronta una modalità di fallimento che BIRD ha evidenziato nei metodi precedenti a prompt singolo: database di grandi dimensioni con schemi rumorosi e domande complesse multi-step sopraffanno i modelli che tentano di ragionare su tutto in un colpo solo.
L'architettura ha tre agenti. Un Selettore riduce un ampio database a un sotto-schema rilevante filtrando tabelle e colonne irrilevanti prima che inizi la generazione dell'SQL. Un Decompositore è il motore centrale — scompone domande in linguaggio naturale complesse in sottoproblemi e genera SQL in modo incrementale con ragionamento few-shot chain-of-thought. Un Raffinatore esegue la query SQL candidata sul database reale, legge i messaggi di errore testuali e corregge iterativamente la query fino a un limite massimo di tentativi. Non tutti e tre gli agenti si attivano per ogni query; i compiti più semplici saltano il Selettore o il Raffinatore in base a segnali di complessità.
Gli autori mettono a punto anche SQL-Llama (Code Llama 7B) sugli output prodotti dal framework, fornendo una variante open-source più piccola.
Idee chiave
- Riduzione dello schema prima della generazione: Il Selettore filtra il database a un sotto-schema rilevante prima che il Decompositore scriva l'SQL. L'ablation conferma un +2,11 punti percentuali sul dev set di BIRD — reale, ma modesto.
- Raffinamento guidato dall'esecuzione: Il Raffinatore legge i messaggi di errore reali del database e corregge l'SQL. Questo è il maggior contributore singolo nell'ablation: rimuoverlo fa calare l'accuratezza sul dev set di BIRD di 4,63 punti, più della rimozione del Selettore (−2,11) o persino del Decompositore (−3,85).
- Invio condizionale degli agenti: Instradare le query più semplici oltre il Selettore e il Raffinatore risparmia token senza danneggiare l'accuratezza sui casi facili.
- Divario nella distillazione open-source: SQL-Llama (7B) raggiunge il 43,94% sul dev set di BIRD rispetto al 46,35% della baseline GPT-4. Il divario non è drammatico data la differenza nel numero di parametri, ma il modello 7B ottimizzato resta indietro di oltre 15 punti rispetto al punteggio completo del 59,59% di GPT-4+MAC-SQL sul test set.
- Risultato sul test BIRD: Accuratezza di esecuzione del 59,59%, al vertice della classifica al momento della sottomissione e superando DAIL-SQL+GPT-4 (57,41%) di 2,18 punti.
Cosa regge — e cosa no
Il Raffinatore è l'idea migliore qui, e l'ablation lo dimostra. Un agente che legge un messaggio di errore reale del database e corregge il proprio SQL sta facendo qualcosa di intrinsecamente più solido di un LLM che ripensa in modo astratto — questo è il principio CRITIC di "critica interattiva con strumenti" applicato direttamente e concretamente al feedback di esecuzione SQL.
Il contributo del Selettore è positivo ma sottile. Per database con centinaia di tabelle probabilmente conta di più; per lo schema tipico di BIRD è marginale, e l'articolo non riporta quanto spesso il Selettore si attiva né la sua precisione nel mantenere le colonne rilevanti — è una scatola nera con un singolo numero aggregato.
Il Decompositore è incrementale rispetto a DIN-SQL. DIN-SQL scomponeva già le query in sottoproblemi con autocorrezione; MAC-SQL ripresenta questo come una conversazione multi-agente. La suddivisione architetturale in tre agenti nominati è più una scelta di design software che un nuovo algoritmo di inferenza. Se la struttura a tre prompt superi un singolo agente con un prompt più lungo, a parità di token totali, non viene mai testato. Le limitazioni riconosciute — prompt "non estesamente ingegnerizzati" e fine-tuning limitato a 7B — sono reali, ma l'omissione più sostanziale è che l'ablation sulla lunghezza del prompt rispetto all'architettura è del tutto assente.
Il contesto temporale è importante per calibrare il giudizio. Il 59,59% di MAC-SQL sul test BIRD era stato dell'arte a dicembre 2023. A metà 2025, la classifica BIRD mostra sistemi che superano l'81%. Le idee specifiche — filtraggio del sotto-schema, scomposizione delle domande, riesecuzione con correzione — sono state assorbite e estese da lavori successivi che utilizzano un addestramento incentrato sul ragionamento, RLVR e CoT più ricco. MAC-SQL come artefatto appare datato; MAC-SQL come schema architetturale rimane attuale.
Perché questo è importante per la finanza AI
Beancount utilizza beanquery — un linguaggio di query affine a SQL — come interfaccia programmatica principale sui dati del registro. Un file beancount reale pluriennale ha uno schema che include decine di conti organizzati in una gerarchia, valute multiple, tag metadati e colonne di saldo calcolato. Questo è precisamente il problema di schema ampio e rumoroso a cui mira il Selettore.
Il Decompositore si applica direttamente ai tipi di domande che gli utenti pongono realmente: "Qual è stata la mia spesa totale per ristorazione in EUR nel terzo trimestre 2024, escludendo le transazioni rimborsate, suddivisa per mese?" è un problema di scomposizione — filtra per prefisso del conto, filtra per intervallo di date, escludi transazioni contrassegnate, aggrega per mese. Il Raffinatore si traduce naturalmente: prima di impegnare una voce beancount generata, un agente potrebbe eseguirla in modalità dry-run attraverso il parser di beancount, ricevere errori di sintassi o di bilancio e rivederla. Il ciclo di feedback di esecuzione che MAC-SQL dimostra è lo stesso ciclo di cui un livello di sicurezza per le scritture ha bisogno.
Il risultato della distillazione open-source è un monito: ottimizzare un modello 7B per approssimare una pipeline basata su GPT-4 produce un modello che è ancora molto indietro. Se Bean Labs costruisce un modello locale per la generazione di query di registro, il divario da MAC-SQL suggerisce che i modelli piccoli necessitano di dati di addestramento specifici del dominio ben oltre ciò che fornisce un fine-tuning generico.
Cosa leggere dopo
- DAIL-SQL (Gao et al., 2023, arXiv:2308.15363) — la valutazione sistematica di benchmarking con ingegneria dei prompt che MAC-SQL supera direttamente su BIRD, utile da leggere per l'ablation controllata della rappresentazione dello schema e della selezione di esempi few-shot
- SQLFixAgent (arXiv:2406.13408) — estende la correzione SQL guidata dall'esecuzione in un sistema multi-agente con controllo di coerenza, un discendente diretto dell'idea del Raffinatore di MAC-SQL
- BIRD-Critic / SWE-SQL (2025) — il nuovo percorso di ragionamento BIRD che richiede la comprensione degli errori di esecuzione, l'evoluzione naturale di ciò che il Raffinatore faceva in MAC-SQL