Soluzioni · Servizi finanziari

Un agente che classifica movimenti di denaro scegliendo da un elenco chiuso, non scrivendo una frase che poi qualcuno interpreta.

In un'organizzazione finanziaria, un agente utile non dà consigli e non approva nulla: legge documenti e transazioni, li inquadra in una categoria da un insieme fisso, dice quanto è sicuro ed è autorizzato a rispondere «non so». Il resto — la decisione, l'approvazione, la politica — rimane alle persone.

Discuti il tuo scenario

Offerta, con condizioniNon scriviamo «consegnato», perché non abbiamo un agente di questo tipo messo in produzione presso un cliente del settore finanziario. Ciò che abbiamo, e mostriamo esattamente come tale, è una pipeline proprietaria di ingestione che gira sui nostri dati: cinque moduli Python, 1.526 righe, che leggono notifiche bancarie da e-mail ed estratti in PDF, classificano ogni transazione tramite strumenti e la scrivono in PostgreSQL con deduplicazione, più quattro flussi di automazione per webhook di tre processori di pagamento. Lo stato reale, detto nella stessa frase: il deposito non è sotto git, le directory `tests/` e `webhook-server/` sono vuote, e il matching approssimativo dei nomi delle controparti usa un’euristica di n-gram marcata nel codice come «da sostituire con un servizio di embedding prima della produzione». La parte di piattaforma finanziaria in produzione — flusso di richiesta, contratto, piano di pagamenti, audit — è un lavoro separato, con le sue prove, e lì scriviamo «consegnato».

Le richieste di agenti AI nei servizi finanziari arrivano quasi sempre nella forma «rispondere ai clienti alle domande sui nostri prodotti». È una richiesta legittima, ma non è lì che si guadagna tempo. Il tempo si perde altrove: qualcuno apre ogni giorno decine di notifiche bancarie e di estratti, guarda una descrizione del tipo di una stringa di maiuscole con un codice e decide se è un incasso da cliente, uno stipendio, un’imposta, una rata verso un creditore o una spesa operativa. Questo lavoro è ripetitivo, noioso e, proprio per questo, pieno di errori.

Un modello linguistico è bravo in questo, a una condizione: che non gli si chieda di scrivere una risposta in testo libero. Se gli chiedete una frase, la parserete voi, e la parsing la sbaglierete. Nella nostra pipeline, il modello non scrive: riceve sette strumenti e deve chiamarne esattamente uno — incasso da cliente, stipendio, imposta, pagamento verso creditore, spesa operativa, commissione bancaria o sconosciuto. Ogni strumento richiede, oltre al nome della controparte o alla categoria, un punteggio di fiducia tra 0 e 1. «Sconosciuto» richiede un motivo scritto. L’output è una struttura, non un’opinione.

La seconda regola è che nulla entra due volte. Ogni transazione estratta da una notifica o da un estratto riceve un identificatore esterno calcolato come prefisso di 16 caratteri di un’impronta SHA-256 sui suoi campi, la colonna è univoca nella tabella, e l’inserimento avviene con `ON CONFLICT (external_id) DO NOTHING`. La conseguenza pratica: la casella di posta può essere riletta quante volte volete, e il saldo non si raddoppia. Senza questa regola, qualunque pipeline di ingestione finanziaria finisce, alla terza settimana, per produrre duplicati che qualcuno pulisce manualmente.

Ciò che un tale agente non fa, e perché è importante scriverlo nella pagina: non approva un pagamento, non prende una decisione di credito, non dà raccomandazioni di investimento e non risponde al cliente a nome dell’istituzione. Il punteggio di fiducia che restituisce è la valutazione del modello su se stesso, non una misurazione dell’accuratezza fatta da noi — questa distinzione è la differenza tra uno strumento e un’illusione di controllo.

Cosa comprende

Cosa cambia concretamente nei servizi finanziari

Il documento entra una sola volta, anche se lo leggiamo dieci volte

Le notifiche si leggono dalla casella di posta tramite IMAP, gli estratti dal PDF. Ogni transazione riceve un identificatore esterno da impronta SHA-256 sui suoi campi, la colonna `external_id` è `NOT NULL UNIQUE` nella tabella, e l’inserimento avviene con `ON CONFLICT (external_id) DO NOTHING`, con log separato per la riga inserita e per quella saltata come duplicato. La rilettura della stessa casella non produce alcun duplicato.

La classificazione si fa tramite strumenti, con un elenco chiuso di risultati

Sette strumenti, non testo libero: incasso da cliente, stipendio, imposta, pagamento verso creditore, spesa operativa, commissione bancaria, sconosciuto. Il modello deve chiamarne uno solo. I primi sei richiedono obbligatoriamente, oltre al nome o alla categoria, un punteggio di fiducia tra 0,0 e 1,0, dichiarato nello schema dello strumento; il settimo richiede un motivo. Il modello utilizzato è dichiarato nel codice, non nascosto nella configurazione.

«Sconosciuto» è un’uscita legittima, con motivo

Un classificatore che non ha il permesso di dire «non so» classificherà male, con alta fiducia, proprio le transazioni insolite — cioè quelle che contano. Per questo lo strumento di sconosciuto è disponibile quanto gli altri e richiede un motivo scritto, che finisce nella riga. Le righe sconosciute sono la lista di lavoro dell’uomo, non un fallimento del sistema.

La corrispondenza approssimativa dei nomi della controparte, con il suo stato reale

La stessa azienda appare negli estratti sotto tre grafie. Sopra la classificazione esiste una corrispondenza per similarità coseno tra vettori. Oggi diciamo esattamente cosa sono quei vettori: un’euristica di n-grammi di caratteri, scritta nel codice con il commento che per la produzione deve essere sostituita con una chiamata reale a un servizio di embedding. Funziona per variazioni di scrittura; non è una corrispondenza semantica.

I webhook dei processori di pagamento entrano nella stessa tabella

Quattro flussi di automazione, uno per ciascuno dei tre processori di pagamento e uno di riconciliazione giornaliera, con 7 fino a 10 nodi ciascuno. L’idea architetturale è che le fonti diverse — e-mail, PDF, webhook — non producono tre tabelle che poi devono essere riconciliate, ma righe nella stessa tabella, con la stessa regola di deduplicazione.

Il consumo del modello resta sotto il budget per chiave, non sotto la fattura

Le chiamate passano attraverso un gateway proprio su `api.megapromoting.com/v1`, con 44 modelli configurati, ciascuno con costo per token e limite di contesto. La chiave di progetto ha una lista bianca di modelli, budget e periodo, si può ruotare mantenendo lo storico, e il consumo viene consolidato giornalmente per utente × chiave × modello. Il dettaglio che sorprende tutti: i modelli di ragionamento producono passaggi interni che il sistema di tracciamento non vede, ma il fornitore li fattura — quindi il budget lordo per chiave si imposta sotto il tetto desiderato.

Cosa si può eseguire senza che i dati escano dalla macchina

Per i passaggi che non richiedono un modello grande — l’estrazione dei campi da un formato noto, l’abbinamento dei nomi, i controlli di coerenza — non serve alcun fornitore esterno; è codice ordinario. Il modello viene chiamato solo per il passaggio di inquadramento. Quando la tua politica vieta l’uscita dei dati, la discussione è che cosa viene inviato al modello, non se si usa l’AI: si può inviare la descrizione della transazione senza gli identificativi del conto.

Cosa non fa e non farà un agente di questo tipo

Non approva un pagamento e non esegue un bonifico. Non prende la decisione di credito — le regole, le soglie e l’approvazione sono la politica dell’istituzione. Non dà raccomandazioni di investimento e non risponde al cliente a tuo nome senza un percorso separato di approvazione. E non ti garantisce l’accuratezza: il punteggio di fiducia è l’output del modello su se stesso, non una misurazione indipendente.

Traseul

Come passa una richiesta attraverso il sistema.

Fissiamo l’elenco chiuso dei risultati, prima di qualsiasi codice

La prima consegna non è un agente, ma una lista: le categorie in cui è autorizzato a classificare, quali campi obbligatori richiede ciascuna, e che cosa significa “sconosciuto” per voi. Se la lista non si può scrivere su una pagina, il compito non è adatto a un agente — ed è più economico scoprirlo ora.

Costruiamo l’ingestione e la deduplicazione, senza modello

La lettura da e-mail, PDF o webhook, l’estrazione dei campi, il calcolo dell’identificativo esterno e la scrittura nella base si fanno e si verificano senza alcuna chiamata a un modello. Consegnamo una pipeline che ingerisce correttamente e non duplica. Se questo passaggio non è solido, un modello sopra di esso produce solo errori più convincenti.

Aggiungiamo l’inquadramento e lo misuriamo sui tuoi casi

Sopra la pipeline che funziona mettiamo gli strumenti di classificazione ed eseguiamo su un insieme di transazioni reali tue, con il risultato corretto stabilito dalla persona che oggi svolge il lavoro. Consegnamo la tabella con gli accordi e i disaccordi, non un’affermazione sull’accuratezza. La soglia da cui la riga va all’uomo si sceglie da quella tabella.

Mettiamo il budget, il log e i gate

Chiave di progetto con lista bianca di modelli e budget, consolidamento giornaliero del consumo, log con lo strumento chiamato e il punteggio, e un gate che invia all’uomo tutto ciò che è sotto soglia o sconosciuto. Consegnamo gli accessi, il documento di messa in esercizio e l’elenco scritto di ciò che l’agente fa da solo e di ciò che non fa.

Il percorso, in 6 passi

I dati

Cosa tocchiamo, dove risiedono e quanto rimangono

Le regole differiscono da un settore all’altro. Queste sono quelle che si applicano nei servizi finanziari.

Che tipo di dati tocca, concretamente: Movimenti di denaro, con data, importo, valuta, descrizione e controparte. Una parte delle controparti sono persone fisiche — uno stipendio porta il nome del dipendente — quindi la tabella contiene dati personali dei dipendenti, non solo dati commerciali. Questo cambia chi ha il permesso di aprire la tabella.
Cosa arriva al modello e cosa resta a casa: Al modello arrivano il testo della descrizione della transazione e l’importo. Gli identificativi di conto, gli IBAN e gli altri campi non hanno posto nella richiesta affinché l’inquadramento funzioni, quindi possono essere lasciati fuori. La regola che applichiamo in generale: ciò che non è necessario per quel passaggio non si invia, perché ciò che non parte non può essere trattenuto da nessuno.
Dove vengono conservati i dati estratti: PostgreSQL, con `external_id` univoco e indice su di esso. Il database resta vostro, sulla vostra infrastruttura o su una che gestiamo noi per voi. Non esiste un deposito comune tra clienti, perché non esiste un motivo tecnico per cui dovrebbe esistere.
Traccia della decisione automatica: Ogni riga conserva quale strumento è stato chiamato, con quale punteggio e, quando è il caso, il motivo di «sconosciuto». È il minimo necessario affinché tra sei mesi qualcuno possa rispondere alla domanda «perché questa transazione è stata classificata come spesa operativa» — con una risposta, non con un’alzata di spalle.
Il termine di conservazione, che qui non scegli da solo: I documenti finanziari hanno termini di conservazione stabiliti dalla normativa contabile e fiscale, non dalla nostra o dalla vostra preferenza. In un progetto finanziario il termine si ricava da quelle regole, si scrive nel registro dei trattamenti e solo dopo si implementa la cancellazione. L’ordine inverso — si implementa prima, si verifica dopo — produce sistemi che cancellano ciò che doveva essere conservato.

Un caso

Una condotta di ingestione che può essere riavviata senza timore

La situazione

Le notifiche bancarie e gli estratti mensili arrivavano in una casella di posta ed erano letti da una persona, che li classificava per categorie. La prima variante evidente — uno script che legge la casella e scrive nel database — ha un problema che si vede solo nella terza settimana: a ogni riavvio o rilettura, le stesse transazioni entrano di nuovo.

Cosa abbiamo costruito

Abbiamo scritto cinque moduli, 1.526 righe di Python: due parser di notifiche tramite IMAP, un estrattore di estratti PDF, il classificatore tramite strumenti e la scrittura in PostgreSQL. La regola centrale è l’identificatore esterno — un prefisso di 16 caratteri da un fingerprint SHA-256 sui campi della transazione — con la colonna univoca nella tabella e inserimento `ON CONFLICT DO NOTHING`. La classificazione non restituisce testo: il modello chiama uno dei sette strumenti, con punteggio di confidenza obbligatorio, e «sconosciuto» richiede un motivo.

Cosa è emerso

La casella di posta può essere riletta in qualsiasi momento, e le righe già elaborate vengono saltate e segnate come duplicate nel registro. Le transazioni che il modello non riesce a classificare compaiono come elenco di lavoro, con il motivo accanto, invece di essere forzate in una categoria per far sembrare che tutto sia andato bene.

Cosa non dice il caso

È una condotta interna, non un sistema consegnato a un cliente finanziario: non è sotto git, le directory di test sono vuote, e l’abbinamento approssimativo dei nomi usa un’euristica di n-grammi che il codice marca esplicitamente come provvisoria. L’ho descritta qui perché mostra il metodo, non perché sia un prodotto.

Domande

Cosa chiede qualcuno nei servizi finanziari

L’agente approva pagamenti o crediti?

No, e non è una limitazione tecnica che supereremo nella prossima versione. L’approvazione è una decisione con conseguenze giuridiche, che spetta a una persona autorizzata dell’istituzione. L’agente prepara: inquadra, completa, segnala ciò che non coincide. Un sistema che approva da solo dovrebbe poter rispondere davanti a un controllore, e un punteggio di confidenza non è una risposta.

Come faccio a sapere che ha classificato correttamente?

Non dal punteggio di confidenza — quello è la valutazione del modello su se stesso, non una misurazione. Si sa dal confronto con le decisioni della persona che oggi svolge il lavoro, su un insieme di transazioni reali, fatto prima di avviare qualcosa in modalità automatica. Il risultato di quel confronto è una tabella che consegniamo, comprese le righe in cui l’agente ha sbagliato.

Cosa succede quando non è sicuro?

Chiamate lo strumento di «unknown» e scrivete il motivo. La riga finisce nella lista di lavoro dell’operatore, non in una categoria scelta a caso per far sembrare che il sistema abbia funzionato. Un classificatore senza uscita «non so» sbaglia esattamente dove l’errore costa: sulle transazioni insolite.

Se leggiamo due volte la stessa notifica, l’importo si raddoppia?

No. Ogni transazione ha un identificatore esterno calcolato come fingerprint sui suoi campi, la colonna è univoca, e l’inserimento usa `ON CONFLICT (external_id) DO NOTHING`. La riga saltata viene annotata nel log come duplicato, quindi si vede che è stata riletta.

I nostri dati vanno a un fornitore di modello?

Per il passaggio di classificazione, sì: la descrizione della transazione e l’importo vanno al modello scelto, tramite il nostro gateway, con chiave di progetto, elenco bianco di modelli e budget. Gli altri passaggi — lettura, estrazione, deduplicazione, matching dei nomi — sono codice comune e non escono da nessuna parte. Cosa è autorizzato a uscire si stabilisce per iscritto prima, non si scopre dai log dopo.

Potete leggere estratti in PDF, non solo notifiche via e-mail?

Sì, è uno dei moduli della pipeline. Da sapere è che un estratto PDF è un formato fragile: si legge secondo la struttura prodotta da quella banca, e quando la banca cambia il template, il modulo va adattato. Per questo si scrive con verifiche che falliscono in modo rumoroso, non che indovinano.

Perché su questa pagina c’è scritto «offerta» e non «consegnato»?

Perché la nostra regola richiede almeno due implementazioni proprie per scrivere «consegnato», e la pipeline descritta qui gira sui nostri dati, non in produzione presso un cliente del settore finanziario. Ha anche delle mancanze che chiamiamo per nome: non è sotto git, non ha test, e il matching dei nomi usa un’euristica marcata nel codice come provvisoria. Quando potremo citare due implementazioni presso clienti, cambiamo la parola.

Di cosa abbiamo bisogno da parte nostra per iniziare il lavoro?

Tre cose: l’elenco chiuso delle categorie in cui può classificare, un insieme di transazioni reali con la risposta corretta fornita dalla persona che svolge oggi il lavoro, e la decisione scritta su quali campi possono uscire dalla vostra rete. Senza il terzo punto non iniziamo, perché è l’unico che non si può correggere in seguito.

Il servizio, in dettaglio Tutti gli scenari

Cosa vorresti che funzionasse meglio?

Raccontaci il tuo processo. Insieme stabiliamo cosa vale la pena costruire, cosa possiamo collegare e come verifichiamo il risultato.

Parliamone