- Pubblicato
- Aggiornato
- Tempo di lettura
- 5 min
Ogni record spiega sé stesso: il serializzatore ai_context
Cyril dà ai suoi record principali un serializzatore ai_context, una vista deterministica e consapevole dello schema, costruita per il modello e non per il database. È il cuore poco appariscente di ciò che fa funzionare davvero il grounding dell’AI.
In questa pagina
La parte entusiasmante del software nativo AI è l’agente che fa qualcosa di utile. La parte che lo fa funzionare davvero è noiosa: come un record si descrive a un modello.
Se la sbagli, ogni demo a valle è costruita sulla sabbia. Se la fai bene, l’agente smette di tirare a indovinare.
Le righe grezze sono l’input sbagliato
Una riga del database è fatta per il database. Ha chiavi esterne, valori enumerati di stato, colonne che possono essere nulle, flag interni e orari in UTC. Dalla a un modello e gli hai chiesto due lavori insieme: ricostruire cosa significa il record, e poi ragionarci sopra.
Il primo lavoro lo farà male. status: 3 non significa nulla senza la tabella di riferimento. Un null in closed_at può voler dire «ancora aperto» oppure «mai registrato». Una chiave esterna è un numero che il modello non sa seguire. Così il modello si inventa il significato che gli serve, con sicurezza, e l’errore si moltiplica a ogni passaggio successivo.
La soluzione non è un modello più grande. È dargli l’input giusto.
Cos’è un serializzatore ai_context
In Cyril i record principali (account, contatti, trattative, progetti, ticket, fatture, documenti e prodotti) espongono ciascuno un serializzatore ai_context. È un unico metodo che restituisce una vista del record deterministica e consapevole dello schema, costruita apposta per il grounding dell’AI.
Quella vista fa l’interpretazione che il modello non dovrebbe fare:
- I valori enumerati vengono tradotti nel loro significato umano:
status: 3diventa"stage: negotiation". - I conteggi collegati vengono inclusi: un account porta con sé il numero di ticket aperti, lo stato dei progetti attivi e quello delle fatture da incassare, perché è ciò che servirà a una domanda su quell’account.
- I campi solo interni vengono rimossi: il modello non vede mai gli ID delle righe, i flag di cancellazione logica o i meccanismi dei tenant.
- La forma è stabile: lo stesso record produce sempre lo stesso contesto, quindi i prompt si possono mettere in cache e il comportamento è riproducibile.
Volutamente, non è la risposta dell’API e non è la riga del database. È una terza rappresentazione il cui unico destinatario è un modello.
Perché la copertura è tutto il punto
Sarebbe facile scrivere un serializzatore ai_context per le tre entità che tocca una demo di lancio. È proprio la trappola. Il valore di un unico grafo di dati è che una domanda può attraversare qualsiasi confine: «quali clienti a rischio hanno anche un progetto in ritardo e una fattura non pagata?» funziona solo se account, progetti e fatture si spiegano tutti allo stesso modo.
Per questo in Cyril il serializzatore è un requisito, non una funzione. Oggi i record principali ne hanno uno; attività, spese, registrazioni delle ore e record HR sono ancora in arrivo, e nessun test automatico verifica ancora che ogni nuova entità ne abbia uno. È una disciplina poco appariscente, ed è esattamente ciò che permette a un agente di attraversare la piattaforma senza incontrare un record che non sa leggere.
Il determinismo è anche una proprietà di sicurezza
Poiché il serializzatore è l’unica vista rivolta all’AI, è anche il punto in cui controlliamo l’esposizione. Le decisioni, campo per campo, su ciò che un agente può vedere stanno in un unico punto verificabile per ogni entità, limitato da org_id come ogni altra query. Non c’è un percorso di «esportazione per l’AI» separato che allarga in silenzio il raggio d’azione: lo stesso serializzatore che fonda il modello è lo stesso confine che lo limita.
Cosa ti dà
- Fai una domanda che attraversa i moduli e ottieni una risposta fondata su dati interpretati, collegati e aggiornati, non su righe grezze che il modello ha dovuto decifrare.
- Fidati della risposta abbastanza da agire, perché lo stesso record produce sempre lo stesso contesto.
- Sai che ciò che l’AI può vedere è definito in un solo posto per ogni entità, non sparso fra le integrazioni.
Il serializzatore non sarà mai la funzione da copertina. È il livello che decide se le funzioni da copertina sono vere.
Domande frequenti
In cosa è diverso dalla risposta dell’API?
La risposta dell’API è pensata per uno sviluppatore che costruisce una schermata: è completa, normalizzata e presuppone che chi la chiama conosca il dominio. Il serializzatore è pensato per un lettore che non conosce lo schema e non sa seguire una chiave esterna, quindi interpreta invece di rimandare.
Perché non fare semplicemente retrieval sul database?
Il retrieval trova testo che somiglia alla domanda. Risponde con ciò che è stato scritto a un certo punto, non con ciò che è vero oggi di un record, e per «quali clienti sono a rischio questo trimestre» ciò che è vero oggi è tutta la domanda.
Costruire questa vista rallenta le query?
Lo stato collegato che include è quello di cui una risposta vera avrebbe avuto comunque bisogno; raccoglierlo una volta, in modo deterministico, costa meno che lasciare che il modello lo chieda in più passaggi. Il determinismo rende anche il risultato memorizzabile in cache, cosa che con le righe grezze non succede.
Cosa succede quando si aggiunge una nuova entità?
Non dovrebbe essere rilasciata senza. Oggi è una regola che ci imponiamo, non una che un test fa rispettare, perché il valore del grafo è che una domanda può attraversare qualsiasi confine: un’entità senza serializzatore è un buco in cui un agente cade.
